Struct libimagstore::store::Store

pub struct Store { /* fields omitted */ }

The Store itself, through this object one can interact with IMAG's entries

Methods

impl Store

pub fn new(location: PathBuf, store_config: &Option<Value>) -> Result<Store>

Create a new Store object

This opens a Store in location. The store_config is used to check whether creating the store implicitely is allowed.

If the location does not exist, creating directories is by default denied and the operation fails, if not configured otherwise. An error is returned in this case.

If the path exists and is a file, the operation is aborted as well, an error is returned.

Return values

• On success: Store object

pub fn new_with_backend(
    location: PathBuf,
    store_config: &Option<Value>,
    backend: Box<FileAbstraction>
) -> Result<Store>

Create a Store object as descripbed in Store::new() documentation, but with an alternative backend implementation.

Do not use directly, only for testing purposes.

pub fn reset_backend(&mut self, backend: Box<FileAbstraction>) -> Result<()>

Reset the backend of the store during runtime

Warning

This is dangerous! You should not be able to do that in application code, only the libimagrt should be used to do this via safe and careful wrapper functions!

If you are able to do this without using libimagrt, please file an issue report.

Purpose

With the I/O backend of the store, the store is able to pipe itself out via (for example) JSON. But because we need a functionality where we load contents from the filesystem and then pipe it to stdout, we need to be able to replace the backend during runtime.

This also applies the other way round: If we get the store from stdin and have to persist it to stdout, we need to be able to replace the in-memory backend with the real filesystem backend.

pub fn create<'a, S: IntoStoreId>(&'a self, id: S) -> Result<FileLockEntry<'a>>

Creates the Entry at the given location (inside the entry)

Return value

On success: FileLockEntry

On error:

• Errors StoreId::into_storeid() might return
• EntryAlreadyExists(id) if the entry exists
• CreateCallError(LockPoisoned()) if the internal lock is poisened.
• CreateCallError(EntryAlreadyExists()) if the entry exists already.

pub fn retrieve<'a, S: IntoStoreId>(
    &'a self,
    id: S
) -> Result<FileLockEntry<'a>>

Borrow a given Entry. When the FileLockEntry is either updated or dropped, the new Entry is written to disk

Implicitely creates a entry in the store if there is no entry with the id id. For a non-implicitely-create look at Store::get.

Return value

On success: FileLockEntry

On error:

• Errors StoreId::into_storeid() might return
• RetrieveCallError(LockPoisoned()) if the internal lock is poisened.

pub fn get<'a, S: IntoStoreId + Clone>(
    &'a self,
    id: S
) -> Result<Option<FileLockEntry<'a>>>

Get an entry from the store if it exists.

Return value

On success: Some(FileLockEntry) or None

On error:

• Errors StoreId::into_storeid() might return
• Errors Store::retrieve() might return

pub fn retrieve_for_module(&self, mod_name: &str) -> Result<StoreIdIterator>

Iterate over all StoreIds for one module name

Returns

On success: An iterator over all entries in the module

On failure:

• (if the glob or one of the intermediate fail)
• RetrieveForModuleCallError(GlobError(EncodingError())) if the path string cannot be encoded
• GRetrieveForModuleCallError(GlobError(lobError())) if the glob() failed.

Important traits for Walk

impl Iterator for Walk type Item = StoreObject;

pub fn walk<'a>(&'a self, mod_name: &str) -> Walk

Walk the store tree for the module

The difference between a Walk and a StoreIdIterator is that with a Walk, one can find "collections" (folders).

pub fn update<'a>(&'a self, entry: &mut FileLockEntry<'a>) -> Result<()>

Write (update) the FileLockEntry to disk

Return value

On success: Entry

On error:

• UpdateCallError(LockPoisoned()) if the internal write lock cannot be aquierd.
• IdNotFound() if the entry was not found in the stor
• Errors Entry::verify() might return
• Errors StoreEntry::write_entry() might return

pub fn get_copy<S: IntoStoreId>(&self, id: S) -> Result<Entry>

Get a copy of a given entry, this cannot be used to mutate the one on disk

Return value

On success: Entry

On error:

• RetrieveCopyCallError(LockPoisoned()) if the internal write lock cannot be aquierd.
• RetrieveCopyCallError(IdLocked()) if the Entry is borrowed currently
• Errors StoreEntry::new() might return

pub fn delete<S: IntoStoreId>(&self, id: S) -> Result<()>

Delete an entry

Return value

On success: ()

On error:

• DeleteCallError(LockPoisoned()) if the internal write lock cannot be aquierd.
• DeleteCallError(FileNotFound()) if the StoreId refers to a non-existing entry.
• DeleteCallError(FileError()) if the internals failed to remove the file.

pub fn save_to(&self, entry: &FileLockEntry, new_id: StoreId) -> Result<()>

Save a copy of the Entry in another place

pub fn save_as(&self, entry: FileLockEntry, new_id: StoreId) -> Result<()>

Save an Entry in another place Removes the original entry

pub fn move_by_id(&self, old_id: StoreId, new_id: StoreId) -> Result<()>

Move an entry without loading

This function moves an entry from one path to another.

Generally, this function shouldn't be used by library authors, if they "just" want to move something around. A library for moving entries while caring about meta-data and links.

Errors

This function returns an error in certain cases:

• If the about-to-be-moved entry is borrowed
• If the lock on the internal data structure cannot be aquired
• If the new path already exists
• If the about-to-be-moved entry does not exist
• If the FS-operation failed

Warnings

This should be used with great care, as moving an entry from a to b might result in dangling links (see below).

Moving linked entries

If the entry which is moved is linked to another entry, these links get invalid (but we do not detect this here). As links are always two-way-links, so a is not only linked to b, but also the other way round, moving b to c results in the following scenario:

• a links to b, which does not exist anymore.
• c links to a, which does exist.

So the link is partly dangling, so to say.

pub fn entries<'a>(&'a self) -> Result<StoreIdIteratorWithStore<'a>>

Get all entries in the store (by id as iterator)

pub fn path(&self) -> &PathBuf

Gets the path where this store is on the disk

Trait Implementations

impl Debug for Store

fn fmt(&self, fmt: &mut Formatter) -> RResult<(), FMTError>

Formats the value using the given formatter.

impl Drop for Store

fn drop(&mut self)

Unlock all files on drop TODO: Unlock them