Introduce Interfaces to Support atomic conditional-writes

server/src/main/java/org/opensearch/common/blobstore/BlobContainer.java

@@ -125,6 +125,40 @@ default long readBlobPreferredLength() {
         throw new UnsupportedOperationException(); // NORELEASE
     }
 
+    /**
+     * Reads blob content from the input stream and writes it to the container in a new blob with the given name,
+     * with conditional verification. The upload succeeds only if {@code verificationTag} matches the remote store’s
+     * current identifier. The operation is atomic: on failure, no changes are applied.
+     * The {@code verificationTagListener} is invoked with the new identifier if the operation succeeds,
+     * or with an error if the write fails.
+     *
+     * @param   blobName
+     *          The name of the blob to write the contents of the input stream to.
+     * @param   inputStream
+     *          The input stream from which to retrieve the bytes to write to the blob.
+     * @param   blobSize
+     *          The size of the blob to be written, in bytes.  It is implementation dependent whether
+     *          this value is used in writing the blob to the repository.
+     * @param   failIfAlreadyExists
+     *          whether to throw a FileAlreadyExistsException if the given blob already exists
+     * @param   verificationTag         Required identifier for conditional upload. The write will only succeed
+     *                                if this matches the remote store’s current identifier.
+     * @param   verificationTagListener Listener to receive the new identifier on success, or to be notified of failure.
+     * @throws  FileAlreadyExistsException if failIfAlreadyExists is true and a blob by the same name already exists
+     * @throws  IOException if the input stream could not be read, the upload fails (including identifier mismatches), or the target blob
+     *                     could not be written to
+     */
+    default void writeBlobIfVerified(
+        String blobName,
+        InputStream inputStream,
+        long blobSize,
+        boolean failIfAlreadyExists,
+        String verificationTag,
+        ActionListener<String> verificationTagListener
+    ) throws IOException {
+        throw new UnsupportedOperationException("writeBlobIfVerified is not implemented yet");
+    }
+
     /**
      * Reads blob content from the input stream and writes it to the container in a new blob with the given name.
      * This method assumes the container does not already contain a blob of the same blobName.  If a blob by the
@@ -144,6 +178,47 @@ default long readBlobPreferredLength() {
      */
     void writeBlob(String blobName, InputStream inputStream, long blobSize, boolean failIfAlreadyExists) throws IOException;
 
+    /**
+     * Reads blob content from the input stream and writes it to the container in a new blob with the given name,
+     * attaching the provided metadata and with conditional verification. The upload succeeds only if {@code verificationTag}
+     * matches the remote store’s current identifier. The operation is atomic: on failure, no changes are applied.
+     * <p>
+     * The {@code verificationTagListener} is invoked with the new identifier if the operation succeeds,
+     * or with an error if the write fails.
+     *
+     * @param   blobName
+     *          The name of the blob to write the contents of the input stream to.
+     * @param   inputStream
+     *          The input stream from which to retrieve the bytes to write to the blob.
+     * @param   metadata
+     *          The metadata to be associate with the blob upload.
+     * @param   blobSize
+     *          The size of the blob to be written, in bytes.  It is implementation dependent whether
+     *          this value is used in writing the blob to the repository.
+     * @param   failIfAlreadyExists
+     *          whether to throw a FileAlreadyExistsException if the given blob already exists
+     * @param   verificationTag
+     *          Required identifier for conditional upload. The write will only succeed
+     *          if this matches the remote store’s current identifier.
+     * @param   verificationTagListener
+     *          Listener to receive the new identifier on success, or to be notified of failure.
+     * @throws  FileAlreadyExistsException if failIfAlreadyExists is true and a blob by the same name already exists
+     * @throws  IOException if the input stream could not be read, the upload fails (including identifier mismatches), or the target blob
+     *                     could not be written to
+     */
+    @ExperimentalApi
+    default void writeBlobWithMetadataIfVerified(
+        String blobName,
+        InputStream inputStream,
+        long blobSize,
+        boolean failIfAlreadyExists,
+        @Nullable Map<String, String> metadata,
+        String verificationTag,
+        ActionListener<String> verificationTagListener
+    ) throws IOException {
+        throw new UnsupportedOperationException("writeBlobWithMetadataIfVerified is not implemented yet");
+    }
+
     /**
      * Reads blob content from the input stream and writes it to the container in a new blob with the given name, and metadata.
      * This method assumes the container does not already contain a blob of the same blobName. If a blob by the