pub struct Object { /* private fields */ }
Expand description
Handler for all object related operations.
Implementations
sourceimpl Object
impl Object
sourcepub fn new(acc: Arc<dyn Accessor>, path: &str) -> Self
pub fn new(acc: Arc<dyn Accessor>, path: &str) -> Self
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.
sourcepub fn id(&self) -> String
pub fn id(&self) -> String
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, likepath/to/dir/test_object
Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;
use opendal::Scheme;
#[tokio::main]
async fn main() -> Result<()> {
let op = Operator::from_env(Scheme::Memory)?;
let id = op.object("test").id();
Ok(())
}
sourcepub fn path(&self) -> &str
pub fn path(&self) -> &str
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;
use opendal::Scheme;
#[tokio::main]
async fn main() -> Result<()> {
let op = Operator::from_env(Scheme::Memory)?;
let path = op.object("test").path();
Ok(())
}
sourcepub fn name(&self) -> &str
pub fn name(&self) -> &str
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;
use opendal::Scheme;
#[tokio::main]
async fn main() -> Result<()> {
let op = Operator::from_env(Scheme::Memory)?;
let name = op.object("test").name();
Ok(())
}
sourcepub async fn create(&self) -> Result<()>
pub async fn create(&self) -> Result<()>
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?;
sourcepub fn blocking_create(&self) -> Result<()>
pub fn blocking_create(&self) -> Result<()>
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()?;
sourcepub async fn read(&self) -> Result<Vec<u8>>
pub async fn read(&self) -> Result<Vec<u8>>
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?;
sourcepub fn blocking_read(&self) -> Result<Vec<u8>>
pub fn blocking_read(&self) -> Result<Vec<u8>>
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()?;
sourcepub async fn range_read(&self, range: impl RangeBounds<u64>) -> Result<Vec<u8>>
pub async fn range_read(&self, range: impl RangeBounds<u64>) -> Result<Vec<u8>>
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 o = op.object("path/to/file");
let bs = o.range_read(1024..2048).await?;
sourcepub fn blocking_range_read(
&self,
range: impl RangeBounds<u64>
) -> Result<Vec<u8>>
pub fn blocking_range_read(
&self,
range: impl RangeBounds<u64>
) -> Result<Vec<u8>>
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)?;
sourcepub async fn reader(&self) -> Result<impl BytesRead>
pub async fn reader(&self) -> Result<impl BytesRead>
Create a new reader which can read the whole object.
Examples
let o = op.object("path/to/file");
let r = o.reader().await?;
sourcepub fn blocking_reader(&self) -> Result<impl BlockingBytesRead>
pub fn blocking_reader(&self) -> Result<impl BlockingBytesRead>
Create a new reader which can read the whole object.
Examples
let o = op.object("path/to/file");
let r = o.blocking_reader()?;
sourcepub async fn range_reader(
&self,
range: impl RangeBounds<u64>
) -> Result<impl BytesRead>
pub async fn range_reader(
&self,
range: impl RangeBounds<u64>
) -> Result<impl BytesRead>
Create a new reader which can read the specified range.
Examples
let o = op.object("path/to/file");
let r = o.range_reader(1024..2048).await?;
sourcepub fn blocking_range_reader(
&self,
range: impl RangeBounds<u64>
) -> Result<impl BlockingBytesRead>
pub fn blocking_range_reader(
&self,
range: impl RangeBounds<u64>
) -> Result<impl BlockingBytesRead>
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)?;
sourcepub fn seekable_reader(&self, range: impl RangeBounds<u64>) -> SeekableReader
pub fn seekable_reader(&self, range: impl RangeBounds<u64>) -> SeekableReader
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);
sourcepub async fn decompress_read(&self) -> Result<Option<Vec<u8>>>
pub async fn decompress_read(&self) -> Result<Option<Vec<u8>>>
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");
sourcepub async fn decompress_reader(&self) -> Result<Option<impl BytesRead>>
pub async fn decompress_reader(&self) -> Result<Option<impl BytesRead>>
sourcepub async fn decompress_read_with(
&self,
algo: CompressAlgorithm
) -> Result<Vec<u8>>
pub async fn decompress_read_with(
&self,
algo: CompressAlgorithm
) -> Result<Vec<u8>>
sourcepub async fn decompress_reader_with(
&self,
algo: CompressAlgorithm
) -> Result<impl BytesRead>
pub async fn decompress_reader_with(
&self,
algo: CompressAlgorithm
) -> Result<impl BytesRead>
sourcepub fn blocking_write_from(
&self,
size: u64,
br: impl BlockingBytesRead + 'static
) -> Result<()>
pub fn blocking_write_from(
&self,
size: u64,
br: impl BlockingBytesRead + 'static
) -> Result<()>
Write data into object from a BlockingBytesRead
.
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)?;
sourcepub fn blocking_delete(&self) -> Result<()>
pub fn blocking_delete(&self) -> Result<()>
sourcepub async fn list(&self) -> Result<DirStreamer>
pub async fn list(&self) -> Result<DirStreamer>
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::from_env(Scheme::Memory)?;
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,
}
}
sourcepub fn blocking_list(&self) -> Result<DirIterator>
pub fn blocking_list(&self) -> Result<DirIterator>
List current dir object.
This function will create a new DirIterator
handle to list objects.
An error will be returned if object path doesn’t end with /
.
Examples
use anyhow::anyhow;
let op = Operator::from_env(Scheme::Memory)?;
let o = op.object("path/to/dir/");
let mut ds = o.blocking_list()?;
while let Some(de) = ds.next() {
let de = de?;
match de.mode() {
ObjectMode::FILE => {
println!("Handling file")
}
ObjectMode::DIR => {
println!("Handling dir like start a new list via meta.path()")
}
ObjectMode::Unknown => continue,
}
}
sourcepub async fn metadata(&self) -> Result<ObjectMetadata>
pub async fn metadata(&self) -> Result<ObjectMetadata>
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")
}
}
sourcepub fn blocking_metadata(&self) -> Result<ObjectMetadata>
pub fn blocking_metadata(&self) -> Result<ObjectMetadata>
Get current object’s metadata.
Examples
use std::io::ErrorKind;
if let Err(e) = op.object("test").blocking_metadata() {
if e.kind() == ErrorKind::NotFound {
println!("object not exist")
}
}
sourcepub async fn is_exist(&self) -> Result<bool>
pub async fn is_exist(&self) -> Result<bool>
Check if this object exists or not.
Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;
use opendal::Scheme;
#[tokio::main]
async fn main() -> Result<()> {
let op = Operator::from_env(Scheme::Memory)?;
let _ = op.object("test").is_exist().await?;
Ok(())
}
sourcepub fn blocking_is_exist(&self) -> Result<bool>
pub fn blocking_is_exist(&self) -> Result<bool>
Check if this object exists or not.
Example
use anyhow::Result;
use opendal::services::memory;
use opendal::Operator;
use opendal::Scheme;
fn main() -> Result<()> {
let op = Operator::from_env(Scheme::Memory)?;
let _ = op.object("test").blocking_is_exist()?;
Ok(())
}
sourcepub fn presign_read(&self, expire: Duration) -> Result<PresignedRequest>
pub fn presign_read(&self, expire: Duration) -> Result<PresignedRequest>
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 = http::Request::builder()
.method(signed_req.method())
.uri(signed_req.uri())
.body(())?;
sourcepub fn presign_write(&self, expire: Duration) -> Result<PresignedRequest>
pub fn presign_write(&self, expire: Duration) -> Result<PresignedRequest>
Presign an operation for write.
Example
use anyhow::Result;
use futures::io;
use opendal::services::memory;
use opendal::Operator;
use time::Duration;
use opendal::Scheme;
#[tokio::main]
async fn main() -> Result<()> {
let signed_req = op.object("test").presign_write(Duration::hours(1))?;
let req = http::Request::builder()
.method(signed_req.method())
.uri(signed_req.uri())
.body(())?;
sourcepub fn to_multipart(&self, upload_id: &str) -> ObjectMultipart
pub fn to_multipart(&self, upload_id: &str) -> ObjectMultipart
Construct a multipart with existing upload id.
sourcepub async fn create_multipart(&self) -> Result<ObjectMultipart>
pub async fn create_multipart(&self) -> Result<ObjectMultipart>
Create a new multipart for current path.
Trait Implementations
Auto Trait Implementations
impl !RefUnwindSafe for Object
impl Send for Object
impl Sync for Object
impl Unpin for Object
impl !UnwindSafe for Object
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for Twhere
V: MultiLane<T>,
impl<V, T> VZip<V> for Twhere
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more