XCOMMONS-3250: Make as easy as possible for various features to use an object store

* Extended the blog store API a bit.
* Added an S3 implementation, the initial draft was by Claude Sonnet 4.
  Untested.

Author: michitux

pom.xml

@@ -137,6 +137,9 @@
     <!-- JAXB -->
     <jaxb.tools.version>2.0.15</jaxb.tools.version>
 
+    <!-- AWS SDK -->
+    <aws.java.sdk.version>2.32.15</aws.java.sdk.version>
+
     <!-- By default, Checkstyle, Backward compatibility check, Enforcer, License plugins, etc., are on -->
     <xwiki.checkstyle.skip>false</xwiki.checkstyle.skip>
     <xwiki.revapi.skip>false</xwiki.revapi.skip>
@@ -1501,6 +1504,13 @@
         <artifactId>jakarta.enterprise.cdi-api</artifactId>
         <version>2.0.2</version>
       </dependency>
+      <dependency>
+        <groupId>software.amazon.awssdk</groupId>
+        <artifactId>bom</artifactId>
+        <version>${aws.java.sdk.version}</version>
+        <type>pom</type>
+        <scope>import</scope>
+      </dependency>
     </dependencies>
   </dependencyManagement>
   <build>

xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/Blob.java

@@ -21,7 +21,6 @@
 
 import java.io.InputStream;
 import java.io.OutputStream;
-import java.nio.file.Path;
 
 import org.xwiki.stability.Unstable;
 import org.xwiki.store.StreamProvider;
@@ -43,12 +42,13 @@ public interface Blob extends StreamProvider
     /**
      * @return the path of this blob inside its store
      */
-    Path getPath();
+    BlobPath getPath();
 
     /**
      * @return true if the blob exists, false otherwise
+     * @throws BlobStoreException when the existence of the blob cannot be determined
      */
-    boolean exists();
+    boolean exists() throws BlobStoreException;
 
     /**
      * Get the size of this blob.
@@ -59,30 +59,44 @@ public interface Blob extends StreamProvider
     long getSize() throws BlobStoreException;
 
     /**
+     * @param conditions the conditions that must be satisfied before writing to this blob
      * @return an OutputStream to write data to this blob
      * @throws BlobStoreException if the blob cannot be written, for example because its name is invalid. There is no
      *     guarantee that in such a case an exception will be thrown, the exception could also only be thrown when data
      *     is written to the stream, or when the stream is closed.
      */
-    OutputStream getOutputStream() throws BlobStoreException;
+    OutputStream getOutputStream(WriteCondition... conditions) throws BlobStoreException;
 
     /**
      * Write the content of the given InputStream to this blob.
      *
      * @param inputStream the InputStream to read data from
+     * @param conditions the conditions that must be satisfied before writing to this blob
      * @throws BlobStoreException if the InputStream cannot be read or the blob cannot be written, for example because
      * its name is invalid.
      */
-    void writeFromStream(InputStream inputStream) throws BlobStoreException;
+    void writeFromStream(InputStream inputStream, WriteCondition... conditions) throws BlobStoreException;
+
+    /**
+     * Get an InputStream to read data from this blob.
+     *
+     * @return an InputStream to read data from this blob
+     * @throws Exception if the blob cannot be read
+     * @throws BlobNotFoundException if the blob does not exist
+     */
+    @Override
+    InputStream getStream() throws Exception;
 
     /**
      * Copy this blob to another path within the same store.
      *
      * @param targetPath the target path for the copy
      * @return the new blob at the target path
      * @throws BlobStoreException if the copy operation fails, for example because this blob doesn't exist
+     * @throws BlobNotFoundException if this blob does not exist
+     * @throws BlobAlreadyExistsException if a blob already exists at the target path
      */
-    default Blob copyTo(Path targetPath) throws BlobStoreException
+    default Blob copyTo(BlobPath targetPath) throws BlobStoreException
     {
         return getStore().copyBlob(getPath(), targetPath);
     }

xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/BlobAlreadyExistsException.java

@@ -0,0 +1,75 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.store.blob;
+
+import java.io.Serial;
+
+import org.xwiki.stability.Unstable;
+
+/**
+ * Exception thrown when trying to copy a blob to a target path that already contains a blob.
+ *
+ * @version $Id$
+ * @since 17.7.0RC1
+ */
+@Unstable
+public class BlobAlreadyExistsException extends BlobStoreException
+{
+    /**
+     * Provides an id for serialization.
+     */
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private static final String BLOB_ALREADY_EXISTS_MESSAGE = "Blob already exists at target path: ";
+
+    private final BlobPath targetPath;
+
+    /**
+     * Constructs a new exception with the specified target path.
+     *
+     * @param targetPath the path where a blob already exists
+     */
+    public BlobAlreadyExistsException(BlobPath targetPath)
+    {
+        super(BLOB_ALREADY_EXISTS_MESSAGE + targetPath);
+        this.targetPath = targetPath;
+    }
+
+    /**
+     * Constructs a new exception with the specified target path and cause.
+     *
+     * @param targetPath the path where a blob already exists
+     * @param cause the cause of the exception
+     */
+    public BlobAlreadyExistsException(BlobPath targetPath, Throwable cause)
+    {
+        super(BLOB_ALREADY_EXISTS_MESSAGE + targetPath, cause);
+        this.targetPath = targetPath;
+    }
+
+    /**
+     * @return the path where a blob already exists
+     */
+    public BlobPath getTargetPath()
+    {
+        return this.targetPath;
+    }
+}

xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/BlobDoesNotExistCondition.java

@@ -0,0 +1,55 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.store.blob;
+
+import org.xwiki.stability.Unstable;
+
+/**
+ * A write condition that requires the blob to not exist before writing.
+ * This ensures atomic create-only operations.
+ *
+ * @version $Id$
+ * @since 17.7.0RC1
+ */
+@Unstable
+public final class BlobDoesNotExistCondition implements WriteCondition
+{
+    /**
+     * Singleton instance of this condition.
+     */
+    public static final BlobDoesNotExistCondition INSTANCE = new BlobDoesNotExistCondition();
+
+    private BlobDoesNotExistCondition()
+    {
+        // Singleton pattern
+    }
+
+    @Override
+    public String getDescription()
+    {
+        return "Blob must not exist";
+    }
+
+    @Override
+    public String toString()
+    {
+        return getDescription();
+    }
+}

xwiki-commons-core/xwiki-commons-store/xwiki-commons-store-blob/xwiki-commons-store-blob-api/src/main/java/org/xwiki/store/blob/BlobNotFoundException.java

@@ -0,0 +1,75 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.store.blob;
+
+import java.io.Serial;
+
+import org.xwiki.stability.Unstable;
+
+/**
+ * Exception thrown when a blob cannot be found at the specified path.
+ *
+ * @version $Id$
+ * @since 17.7.0RC1
+ */
+@Unstable
+public class BlobNotFoundException extends BlobStoreException
+{
+    /**
+     * Provides an id for serialization.
+     */
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    private static final String BLOB_NOT_FOUND_MESSAGE = "Blob not found at path: ";
+
+    private final BlobPath blobPath;
+
+    /**
+     * Constructs a new exception with the specified blob path.
+     *
+     * @param blobPath the path of the blob that was not found
+     */
+    public BlobNotFoundException(BlobPath blobPath)
+    {
+        super(BLOB_NOT_FOUND_MESSAGE + blobPath);
+        this.blobPath = blobPath;
+    }
+
+    /**
+     * Constructs a new exception with the specified blob path and cause.
+     *
+     * @param blobPath the path of the blob that was not found
+     * @param cause the cause of the exception
+     */
+    public BlobNotFoundException(BlobPath blobPath, Throwable cause)
+    {
+        super(BLOB_NOT_FOUND_MESSAGE + blobPath, cause);
+        this.blobPath = blobPath;
+    }
+
+    /**
+     * @return the path of the blob that was not found
+     */
+    public BlobPath getBlobPath()
+    {
+        return this.blobPath;
+    }
+}