Trait ObjectStoreExt 

pub trait ObjectStoreExt: ObjectStore {
    // Required methods
    fn put(
        &self,
        location: &Path,
        payload: PutPayload,
    ) -> impl Future<Output = Result<PutResult>>;
    fn put_multipart(
        &self,
        location: &Path,
    ) -> impl Future<Output = Result<Box<dyn MultipartUpload>>>;
    fn get(&self, location: &Path) -> impl Future<Output = Result<GetResult>>;
    fn get_range(
        &self,
        location: &Path,
        range: Range<u64>,
    ) -> impl Future<Output = Result<Bytes>>;
    fn head(&self, location: &Path) -> impl Future<Output = Result<ObjectMeta>>;
    fn delete(&self, location: &Path) -> impl Future<Output = Result<()>>;
    fn copy(&self, from: &Path, to: &Path) -> impl Future<Output = Result<()>>;
    fn copy_if_not_exists(
        &self,
        from: &Path,
        to: &Path,
    ) -> impl Future<Output = Result<()>>;
    fn rename(&self, from: &Path, to: &Path) -> impl Future<Output = Result<()>>;
    fn rename_if_not_exists(
        &self,
        from: &Path,
        to: &Path,
    ) -> impl Future<Output = Result<()>>;
}

Extension trait for ObjectStore with convenience functions.

See the module-level documentation for a high level overview and examples. See “contract” section within the ObjectStore documentation for more reasoning.

Implementation

You MUST NOT implement this trait yourself. It is automatically implemented for all ObjectStore implementations.

Required Methods

fn put( &self, location: &Path, payload: PutPayload, ) -> impl Future<Output = Result<PutResult>>

Save the provided bytes to the specified location

The operation is guaranteed to be atomic, it will either successfully write the entirety of payload to location, or fail. No clients should be able to observe a partially written object

fn put_multipart( &self, location: &Path, ) -> impl Future<Output = Result<Box<dyn MultipartUpload>>>

Perform a multipart upload

Client should prefer ObjectStoreExt::put for small payloads, as streaming uploads typically require multiple separate requests. See MultipartUpload for more information

For more advanced multipart uploads see MultipartStore

fn get(&self, location: &Path) -> impl Future<Output = Result<GetResult>>

Return the bytes that are stored at the specified location.

Example

This example uses a basic local filesystem object store to get an object.

async fn get_example() {
    let tmp = tempdir().unwrap();
    let store = LocalFileSystem::new_with_prefix(tmp.path()).unwrap();
    let location = Path::from("example.txt");
    let content = b"Hello, Object Store!";

    // Put the object into the store
    store
        .put(&location, content.as_ref().into())
        .await
        .expect("Failed to put object");

    // Get the object from the store
    let get_result = store.get(&location).await.expect("Failed to get object");
    let bytes = get_result.bytes().await.expect("Failed to read bytes");
    println!("Retrieved content: {}", String::from_utf8_lossy(&bytes));
}

fn get_range( &self, location: &Path, range: Range<u64>, ) -> impl Future<Output = Result<Bytes>>

Return the bytes that are stored at the specified location in the given byte range.

See GetRange::Bounded for more details on how range gets interpreted.

To retrieve a range of bytes from a versioned object, use ObjectStore::get_opts by specifying the range in the GetOptions.

Examples

This example uses a basic local filesystem object store to get a byte range from an object.

async fn get_range_example() {
    let tmp = tempdir().unwrap();
    let store = LocalFileSystem::new_with_prefix(tmp.path()).unwrap();
    let location = Path::from("example.txt");
    let content = b"Hello, Object Store!";

    // Put the object into the store
    store
        .put(&location, content.as_ref().into())
        .await
        .expect("Failed to put object");

    // Get the object from the store
    let bytes = store
        .get_range(&location, 0..5)
        .await
        .expect("Failed to get object");
    println!("Retrieved range [0-5]: {}", String::from_utf8_lossy(&bytes));
}

fn head(&self, location: &Path) -> impl Future<Output = Result<ObjectMeta>>

Return the metadata for the specified location

fn delete(&self, location: &Path) -> impl Future<Output = Result<()>>

Delete the object at the specified location.

fn copy(&self, from: &Path, to: &Path) -> impl Future<Output = Result<()>>

Copy an object from one path to another in the same object store.

If there exists an object at the destination, it will be overwritten.

fn copy_if_not_exists( &self, from: &Path, to: &Path, ) -> impl Future<Output = Result<()>>

Copy an object from one path to another, only if destination is empty.

Will return an error if the destination already has an object.

Performs an atomic operation if the underlying object storage supports it. If atomic operations are not supported by the underlying object storage (like S3) it will return an error.

fn rename(&self, from: &Path, to: &Path) -> impl Future<Output = Result<()>>

Move an object from one path to another in the same object store.

By default, this is implemented as a copy and then delete source. It may not check when deleting source that it was the same object that was originally copied.

If there exists an object at the destination, it will be overwritten.

fn rename_if_not_exists( &self, from: &Path, to: &Path, ) -> impl Future<Output = Result<()>>

Move an object from one path to another in the same object store.

Will return an error if the destination already has an object.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T> ObjectStoreExt for T

where T: ObjectStore + ?Sized,