Struct opendal::Object

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

Object is the handler for all object related operations.

Notes

Object will cache part of object metadata that pre-fetch by list or stat operations. It’s better to reuse the same object whenever possible.

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.

Fetch the operator that used by this object.

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::Operator;

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    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::Operator;

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    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::Operator;

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    let name = op.object("test").name();

    Ok(())
}

Return this object entry’s object mode.

Return this object entry’s object mode in blocking way.

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?;

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.blocking_create()?;
Create a dir
let o = op.object("path/to/dir/");
let _ = o.blocking_create()?;

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 o = op.object("path/to/file");
let bs = o.read().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::blocking_reader

Examples
let o = op.object("path/to/file");
let bs = o.blocking_read()?;

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

Notes
  • The returning contnet’s length may be smaller than the range specifed.
Examples
let o = op.object("path/to/file");
let bs = o.range_read(1024..2048).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::blocking_range_reader

Examples
let o = op.object("path/to/file");
let bs = o.blocking_range_read(1024..2048)?;

Create a new reader which can read the whole object.

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

Create a new reader which can read the whole object.

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

Create a new reader which can read the specified range.

Notes
  • The returning contnet’s length may be smaller than the range specifed.
Examples
let o = op.object("path/to/file");
let r = o.range_reader(1024..2048).await?;

Create a new reader which can read the specified range.

Examples
let o = op.object("path/to/file");
let r = o.blocking_range_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?;

Write data with option described in OpenDAL rfc-0661

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 bs = b"hello, world!".to_vec();
let args = OpWrite::new(bs.len() as u64).with_content_type("text/plain");
let _ = o.write_with(args, bs).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.blocking_write(vec![0; 4096])?;

Write data with option described in OpenDAL rfc-0661

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

let o = op.object("hello.txt");
let bs = b"hello, world!".to_vec();
let ow = OpWrite::new(bs.len() as u64).with_content_type("text/plain");
let _ = o.blocking_write_with(ow, bs)?;

Write data into object from a input::Read.

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

let o = op.object("path/to/file");
let r = Cursor::new(vec![0; 4096]);
let _ = o.write_from(4096, r).await?;

Write data into object from a input::BlockingRead.

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

use bytes::Bytes;

let o = op.object("path/to/file");
let r = Cursor::new(vec![0; 4096]);
let _ = o.blocking_write_from(4096, r)?;

Delete object.

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

Delete object.

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

List current dir object.

This function will create a new handle to list objects.

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

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

List current dir object.

This function will create a new handle to list objects.

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

Examples
let o = op.object("path/to/dir/");
let mut ds = o.blocking_list()?;
while let Some(de) = ds.next() {
    let de = de?;
    match de.blocking_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 without cache.

Notes

This function works exactly the same with Object::metadata.The only difference is it will not try to load data from cached metadata.

Use this function to detect the outside changes of object.

Get current object’s metadata with cache.

Notes

This function will try access the local metadata cache first. If there are outside changes of the object, metadata could return out-of-date metadata. To overcome this, please use Object::stat.

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

The size of ObjectEntry’s corresponding object

content_length is a prefetched metadata field in ObjectEntry.

The MD5 message digest of ObjectEntry’s corresponding object

content_md5 is a prefetched metadata field in ObjectEntry

It doesn’t mean this metadata field of object doesn’t exist if content_md5 is None. Then you have to call ObjectEntry::metadata() to get the metadata you want.

The last modified UTC datetime of ObjectEntry’s corresponding object

last_modified is a prefetched metadata field in ObjectEntry

It doesn’t mean this metadata field of object doesn’t exist if last_modified is None. Then you have to call ObjectEntry::metadata() to get the metadata you want.

The ETag string of ObjectEntry’s corresponding object

etag is a prefetched metadata field in ObjectEntry.

It doesn’t mean this metadata field of object doesn’t exist if etag is None. Then you have to call ObjectEntry::metadata() to get the metadata you want.

Get current object’s metadata.

Examples
use opendal::ErrorKind;
if let Err(e) = op.object("test").blocking_metadata() {
    if e.kind() == ErrorKind::ObjectNotFound {
        println!("object not exist")
    }
}

Check if this object exists or not.

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

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

    Ok(())
}

Check if this object exists or not.

Example
use anyhow::Result;
use opendal::Operator;
fn test(op: Operator) -> Result<()> {
    let _ = op.object("test").blocking_is_exist()?;

    Ok(())
}

Presign an operation for stat(head).

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

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

Presign an operation for read.

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

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    let signed_req = op.object("test.txt").presign_read(Duration::hours(1))?;
  • signed_req.method(): GET
  • signed_req.uri(): https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=access_key_id/20130721/us-east-1/s3/aws4_request&X-Amz-Date=20130721T201207Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature-value>
  • signed_req.headers(): { "host": "s3.amazonaws.com" }

We can download this object via curl or other tools without credentials:

curl "https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=access_key_id/20130721/us-east-1/s3/aws4_request&X-Amz-Date=20130721T201207Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature-value>" -O /tmp/test.txt

Presign an operation for write.

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

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    let signed_req = op.object("test.txt").presign_write(Duration::hours(1))?;
  • signed_req.method(): PUT
  • signed_req.uri(): https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=access_key_id/20130721/us-east-1/s3/aws4_request&X-Amz-Date=20130721T201207Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature-value>
  • signed_req.headers(): { "host": "s3.amazonaws.com" }

We can upload file as this object via curl or other tools without credential:

curl -X PUT "https://s3.amazonaws.com/examplebucket/test.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=access_key_id/20130721/us-east-1/s3/aws4_request&X-Amz-Date=20130721T201207Z&X-Amz-Expires=86400&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature-value>" -d "Hello, World!"

Presign an operation for write with option described in OpenDAL rfc-0661

You can pass OpWrite to this method to specify the content length and content type.

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

#[tokio::main]
async fn test(op: Operator) -> Result<()> {
    let args = OpWrite::new(0).with_content_type("text/csv");
    let signed_req = op.object("test").presign_write_with(args, Duration::hours(1))?;
    let req = http::Request::builder()
        .method(signed_req.method())
        .uri(signed_req.uri())
        .body(())?;

Construct a multipart with existing upload id.

Create a new multipart for current path.

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

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

Calls U::from(self).

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

The alignment of pointer.
The type for initializers.
Initializes a with the given initializer. Read more
Dereferences the given pointer. Read more
Mutably dereferences the given pointer. Read more
Drops the object pointed to by the given pointer. Read more
Should always be Self
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
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