pub struct Object { /* private fields */ }
Expand description

Handler for all object related operations.

Implementations

Creates a new Object with normalized path.

  • All path will be converted into relative path (without any leading /)
  • Path endswith / means it’s a dir path.
  • Otherwise, it’s a file path.

ID of object.

ID is the unique id of object in the underlying backend. In different backend, the id could have different meaning.

For example:

  • In fs: id is the absolute path of file, like /path/to/dir/test_object.
  • In s3: id is the full object key, like path/to/dir/test_object
Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let id = op.object("test").id();

    Ok(())
}

Path of object. Path is relative to operator’s root. Only valid in current operator.

The value is the same with Metadata::path().

Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let path = op.object("test").path();

    Ok(())
}

Name of object. Name is the last segment of path.

If this object is a dir, Name MUST endswith / Otherwise, Name MUST NOT endswith /.

The value is the same with Metadata::name().

Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let name = op.object("test").name();

    Ok(())
}

Create an empty object, like using the following linux commands:

  • touch path/to/file
  • mkdir path/to/dir/
Behavior
  • Create on existing dir will succeed.
  • Create on existing file will overwrite and truncate it.
Examples
Create an empty file
let o = op.object("path/to/file");
let _ = o.create().await?;
Create a dir
let o = op.object("path/to/dir/");
let _ = o.create().await?;

Read the whole object into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use Object::reader

Examples
let bs = o.read().await?;

Read the specified range of object into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use Object::range_reader

Examples
let bs = o.range_read(1024..2048).await?;

Create a new reader which can read the whole object.

Examples
let r = o.reader().await?;

Create a new reader which can read the specified range.

Examples
let r = o.range_reader(1024..2048).await?;

Create a reader which implements AsyncRead and AsyncSeek inside specified range.

Notes

It’s not a zero-cost operations. In order to support seeking, we have extra internal state which maintains the reader contents:

  • Seeking is pure in memory operation.
  • Every first read after seeking will start a new read operation on backend.

This operation is neither async nor returning result, because real IO happens while users call read or seek.

Examples
let r = o.seekable_reader(1024..2048);

Read the whole object into a bytes with auto detected compress algorithm.

If we can’t find the correct algorithm, we return Ok(None) instead.

Feature

This function needs to enable feature compress.

Examples
let o = op.object("path/to/file.gz");
let bs = o.decompress_read().await?.expect("must read succeed");

Create a reader with auto detected compress algorithm.

If we can’t find the correct algorithm, we will return Ok(None).

Feature

This function needs to enable feature compress.

Examples
let o = op.object("path/to/file.gz");
let r = o.decompress_reader().await?;

Read the whole object into a bytes with specific compress algorithm.

Feature

This function needs to enable feature compress.

Examples
let o = op.object("path/to/file.gz");
let bs = o.decompress_read_with(CompressAlgorithm::Gzip).await?;

Create a reader with specific compress algorithm.

Feature

This function needs to enable feature compress.

Examples
let o = op.object("path/to/file.gz");
let r = o.decompress_reader_with(CompressAlgorithm::Gzip).await?;

Write bytes into object.

Notes
  • Write will make sure all bytes has been written, or an error will be returned.
Examples
use bytes::Bytes;

let o = op.object("path/to/file");
let _ = o.write(vec![0; 4096]).await?;

Create a new writer which can write data into the object.

Examples
use bytes::Bytes;

let op = Operator::new(memory::Backend::build().finish().await?);
let o = op.object("path/to/file");
let mut w = o.writer(4096).await?;
w.write(&[1; 4096]);
w.close();

Delete object.

Notes
  • Delete not existing error won’t return errors.
Examples
op.object("test").delete().await?;

List current dir object.

This function will create a new DirStreamer handle to list objects.

An error will be returned if object path doesn’t end with /.

Examples
let op = Operator::new(memory::Backend::build().finish().await?);
let o = op.object("path/to/dir/");
let mut ds = o.list().await?;
// DirStreamer implements `futures::Stream`
while let Some(de) = ds.try_next().await? {
    match de.mode() {
        ObjectMode::FILE => {
            println!("Handling file")
        }
        ObjectMode::DIR => {
            println!("Handling dir like start a new list via meta.path()")
        }
        ObjectMode::Unknown => continue,
    }
}

Get current object’s metadata.

Examples
use std::io::ErrorKind;
if let Err(e) = op.object("test").metadata().await {
    if e.kind() == ErrorKind::NotFound {
        println!("object not exist")
    }
}

Check if this object exists or not.

Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;

#[tokio::main]
async fn main() -> Result<()> {
    let op = Operator::new(memory::Backend::build().finish().await?);
    let _ = op.object("test").is_exist().await?;

    Ok(())
}

Presign an operation for read.

Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;
use time::Duration;

#[tokio::main]
async fn main() -> Result<()> {
    let signed_req = op.object("test").presign_read(Duration::hours(1))?;
    let req = hyper::Request::builder()
        .method(signed_req.method())
        .uri(signed_req.uri())
        .body(hyper::Body::empty())?;

Presign an operation for write.

Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;
use time::Duration;

#[tokio::main]
async fn main() -> Result<()> {
    let signed_req = op.object("test").presign_write(Duration::hours(1))?;
    let req = hyper::Request::builder()
        .method(signed_req.method())
        .uri(signed_req.uri())
        .body(hyper::Body::from("Hello, World!"))?;

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

DirEntry can convert into object without overhead.

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Applies the [Compat] adapter by value. Read more

Applies the [Compat] adapter by shared reference. Read more

Applies the [Compat] adapter by mutable reference. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more