HADOOP-19256. S3A: Support S3 Conditional Writes: rename builder()

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FutureRenameOutcomeBuilder.java

@@ -0,0 +1,99 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.hadoop.fs;
+
+import java.io.UncheckedIOException;
+import java.util.concurrent.CompletableFuture;
+import javax.annotation.Nullable;
+
+import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceStability;
+import org.apache.hadoop.util.Progressable;
+
+/**
+ * Builder for input streams and subclasses whose return value is
+ * actually a completable future: this allows for better asynchronous
+ * operation.
+ * <p>
+ * To be more generic, {@link #opt(String, int)} and {@link #must(String, int)}
+ * variants provide implementation-agnostic way to customize the builder.
+ * Each FS-specific builder implementation can interpret the FS-specific
+ * options accordingly, for example:
+ * <p>
+ * If the option is not related to the file system, the option will be ignored.
+ * If the option is must, but not supported/known by the file system, an
+ * {@link IllegalArgumentException} will be thrown.
+ * <p>
+ * See {@see FileContext#rename(Path, Path, Options.Rename..)}.
+ * See {@see FileSystem#rename(Path, Path)}.
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Unstable
+public interface FutureRenameOutcomeBuilder
+    extends FSBuilder<CompletableFuture<RenameOutcome>, FutureRenameOutcomeBuilder> {
+
+  @Override
+  default CompletableFuture<RenameOutcome> build()
+      throws IllegalArgumentException, UnsupportedOperationException,
+             UncheckedIOException {
+    throw new UnsupportedOperationException("unimplemented");
+  }
+
+  /**
+   * An optional status of the source file.
+   * The name of the status MUST match that of the source path;
+   * the rest of the path SHALL NOT be compared.
+   * It is up to the implementation whether to use this or not.
+   * @param status status: may be null
+   * @return the builder.
+   */
+  default FutureRenameOutcomeBuilder withSourceStatus(
+      @Nullable FileStatus status) {
+    return this;
+  }
+
+  default FutureRenameOutcomeBuilder requireAtomic(
+      boolean flag) {
+    return this;
+  }
+
+  default FutureRenameOutcomeBuilder withLegacyPathFixup(
+      boolean flag) {
+    return this;
+  }
+
+  default FutureRenameOutcomeBuilder withProgress(
+      @Nullable Progressable progressable) {
+
+    return this;
+  }
+
+  default FutureRenameOutcomeBuilder withSourceEtag(
+      @Nullable String etag) {
+
+    return this;
+  }
+
+  default FutureRenameOutcomeBuilder withSourceType(
+      @Nullable Options.RenameSourceType type) {
+    return this;
+  }
+
+
+
+}

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/Options.java

@@ -242,6 +242,53 @@ public byte value() {
     }
   }
 
+  /**
+   * Explicit declaration of file type;
+   * Implementations of {@link RenameOperation} may use this.
+   * <p>
+   * If a wrong file type is passed in, the call SHOULD fail;
+   * the failure mode is undefined.
+   * <p>
+   */
+  public enum RenameSourceType {
+
+    /** Source is known to be a file. */
+    File("file"),
+
+    /** Source is known to be a directory. */
+    Directory("directory"),
+
+    /** any type. */
+    Any("any");
+
+    private final String type;
+
+    RenameSourceType(final String type) {
+      this.type = type;
+    }
+
+    /**
+     * Find the matching type, falling back to {@link #Any}
+     * if no other match is found, the string is empty etc.
+     * @param type type to resolve.
+     * @return a valid source type.
+     */
+    public static RenameSourceType resolve(String type) {
+
+      for (RenameSourceType v: values()) {
+        if (v.type.equalsIgnoreCase(type)) {
+          return v;
+        }
+      }
+      return Any;
+    }
+
+    public String value() {
+      return type;
+    }
+
+  }
+
   /**
    * This is used in FileSystem and FileContext to specify checksum options.
    */

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RenameOperation.java

@@ -0,0 +1,31 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.fs;
+
+import org.apache.hadoop.fs.impl.FutureRenameOutcomeBuilderImpl;
+
+/**
+ *
+ */
+public class RenameOperation {
+
+  FutureRenameOutcomeBuilder beginRename(Path source, Path dest) {
+    return new FutureRenameOutcomeBuilderImpl(source, dest);
+  }
+}

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/RenameOutcome.java

@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.fs;
+
+import java.time.Duration;
+
+import static java.util.Objects.requireNonNull;
+
+public class RenameOutcome {
+  private final Duration duration;
+
+  public RenameOutcome(final Duration duration) {
+    this.duration = requireNonNull(duration);
+  }
+
+  public Duration getDuration() {
+    return duration;
+  }
+}

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/impl/FutureRenameOutcomeBuilderImpl.java

@@ -0,0 +1,80 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.hadoop.fs.impl;
+
+import java.util.concurrent.CompletableFuture;
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+import org.apache.hadoop.fs.FileStatus;
+import org.apache.hadoop.fs.FutureRenameOutcomeBuilder;
+import org.apache.hadoop.fs.Path;
+import org.apache.hadoop.fs.RenameOutcome;
+import org.apache.hadoop.util.Progressable;
+
+public class FutureRenameOutcomeBuilderImpl
+    extends AbstractFSBuilderImpl<CompletableFuture<RenameOutcome>, FutureRenameOutcomeBuilder>
+    implements FutureRenameOutcomeBuilder {
+
+
+  @Nonnull private final Path dest;
+
+  private boolean atomic;
+
+  @Nullable private String etag;
+
+  @Nullable private Progressable progressable;
+
+  @Nullable private FileStatus status;
+
+  public FutureRenameOutcomeBuilderImpl(
+      @Nonnull final Path source, @Nonnull final Path dest) {
+    super(source);
+    this.dest = dest;
+  }
+
+  @Override
+  public FutureRenameOutcomeBuilder withSourceStatus(@Nullable final FileStatus status) {
+    this.status = status;
+    return this;
+  }
+
+  @Override
+  public FutureRenameOutcomeBuilder requireAtomic(final boolean atomic) {
+    this.atomic = atomic;
+    return this;
+  }
+
+  @Override
+  public FutureRenameOutcomeBuilder withLegacyPathFixup(final boolean pathFixup) {
+    return this;
+  }
+
+  @Override
+  public FutureRenameOutcomeBuilder withProgress(@Nullable final Progressable progressable) {
+    this.progressable = progressable;
+    return this;
+  }
+
+  @Override
+  public FutureRenameOutcomeBuilder withSourceEtag(@Nullable final String etag) {
+    this.etag = etag;
+    return this;
+  }
+}