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;
#[tokio::main]
async fn main() -> Result<()> {
let op = Operator::new(memory::Backend::build().finish().await?);
let id = op.object("test").id();
Ok(())
}
sourcepub fn path(&self) -> String
pub fn path(&self) -> String
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(())
}
sourcepub fn name(&self) -> String
pub fn name(&self) -> String
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(())
}
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 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 bs = o.read().await?;
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 bs = o.range_read(1024..2048).await?;
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 r = o.range_reader(1024..2048).await?;
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 async fn writer(&self, size: u64) -> Result<impl BytesWrite>
pub async fn writer(&self, size: u64) -> Result<impl BytesWrite>
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();
sourcepub async fn list(&self) -> Result<ObjectStreamer>
pub async fn list(&self) -> Result<ObjectStreamer>
List current dir object.
This function will create a new ObjectStreamer
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 obs = o.list().await?;
// ObjectStream implements `futures::Stream`
while let Some(o) = obs.next().await {
let mut o = o?;
// It's highly possible that OpenDAL already did metadata during list.
// Use `Object::metadata_cached()` to get cached metadata at first.
let meta = o.metadata_cached().await?;
match meta.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<Metadata>
pub async fn metadata(&self) -> Result<Metadata>
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 async fn metadata_cached(&mut self) -> Result<&Metadata>
pub async fn metadata_cached(&mut self) -> Result<&Metadata>
Use local cached metadata if possible.
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 mut o = op.object("test");
o.metadata_cached().await;
// The second call to metadata_cached will have no cost.
o.metadata_cached().await;
Ok(())
}
sourcepub async fn is_exist(&self) -> Result<bool>
pub async fn is_exist(&self) -> Result<bool>
Check if this object exist 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(())
}
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 T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
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>
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
Instruments this type with the provided Span
, returning an
Instrumented
wrapper. Read more
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
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
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