Package org.nuxeo.ecm.core.blob

Interface BlobStore

All Known Implementing Classes:

AbstractBlobStore, AESBlobStore, AzureBlobStore, CachingBlobStore, EmptyBlobStore, GoogleStorageBlobStore, GridFSBlobStore, InMemoryBlobStore, LocalBlobStore, S3BlobStore, TransactionalBlobStore

public interface BlobStore

Interface for basic access to storage of a Blob (read/write/copy/delete).

A blob is identified by a key, and holds a stream of bytes. It may have some associated metadata (filename, content type).

A blob store may have versioning. When this is the case, the write method will return a key that includes a version number. This same complete key must subsequently be provided to the read or delete methods. With versioning, two writes may be requested with the same key in the blob context, and both will succeed because they return keys that include a version number to distinguish them.

Since:

11.1

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	BlobStore.OptionalOrUnknown<T>	A class representing an unknown value, a missing value, or a present (non-null) value.

Method Summary

Modifier and Type	Method	Description
void	clear()	INTERNAL (TESTS).
default boolean	copyBlob(String key, BlobStore sourceStore, String sourceKey, boolean atomicMove)	Deprecated. since 11.5, use copyOrMoveBlob(java.lang.String, org.nuxeo.ecm.core.blob.BlobStore, java.lang.String, boolean) instead
boolean	copyBlobIsOptimized(BlobStore sourceStore)	Checks if blob copy/move from another blob store to this one can be done efficiently.
String	copyOrMoveBlob(String key, BlobStore sourceStore, String sourceKey, boolean atomicMove)	Writes a file based on a key, as an optimized copy/move from a source in another compatible blob store.
void	deleteBlob(String key)	Deletes a blob based on a key.
void	deleteBlob(BlobContext blobContext)	Deletes a blob.
default boolean	exists(String key)	Does a blob with the given key exist in the blob store.
BinaryGarbageCollector	getBinaryGarbageCollector()	Returns the binary garbage collector (GC).
BlobStore.OptionalOrUnknown<Path>	getFile(String key)	Gets an already-existing file containing the blob for the given key, if present.
KeyStrategy	getKeyStrategy()	Gets the key strategy used by the store.
String	getName()	Name used for debugging / tracing.
BlobStore.OptionalOrUnknown<InputStream>	getStream(String key)	Gets the stream of the blob for the given key, if present.
default boolean	hasDefaultStorageClass(String key)	Does a blob with the given key exist in the blob store with the default storage class.
boolean	hasVersioning()	Whether this blob store has versioning.
boolean	readBlob(String key, Path dest)	Reads a blob based on its key into the given file.
BlobStore	unwrap()	If this blob store wraps another one, returns it, otherwise returns this.
String	writeBlob(BlobContext blobContext)	Writes a blob.
String	writeBlob(BlobWriteContext blobWriteContext)	Writes a blob.
void	writeBlobProperties(BlobUpdateContext blobUpdateContext)	Sets properties on a blob.

Method Detail

getName

String getName()

Name used for debugging / tracing.

hasVersioning

boolean hasVersioning()

Whether this blob store has versioning.

With versioning, two writes may use the same key. The returned keys will include a different version number to distinguish the writes.

getKeyStrategy

KeyStrategy getKeyStrategy()

Gets the key strategy used by the store.

writeBlob

String writeBlob(BlobContext blobContext)
          throws IOException

Writes a blob.

Parameters:

blobContext - the blob context

Returns:

the blob key

Throws:

IOException

writeBlob

String writeBlob(BlobWriteContext blobWriteContext)
          throws IOException

Writes a blob.

Note that the returned key may be different than the one requested by the BlobWriteContext, if the blob store needs additional version info to retrieve it.

Parameters:

blobWriteContext - the context of the blob write, including the blob

Returns:

the key to use to read this blob in the future

Throws:

IOException

copyBlobIsOptimized

boolean copyBlobIsOptimized(BlobStore sourceStore)

Checks if blob copy/move from another blob store to this one can be done efficiently.

Parameters:

sourceStore - the source store

Returns:

true if the copy/move can be done efficiently

copyBlob

@Deprecated
default boolean copyBlob(String key,
                         BlobStore sourceStore,
                         String sourceKey,
                         boolean atomicMove)
                  throws IOException

Deprecated.

since 11.5, use copyOrMoveBlob(java.lang.String, org.nuxeo.ecm.core.blob.BlobStore, java.lang.String, boolean) instead

Writes a file based on a key, as a copy/move from a source in another blob store.

If the copy/move is requested to be atomic, then the destination file is created atomically. In case of atomic move, in some stores the destination will be created atomically but the source will only be deleted afterwards.

Parameters:

key - the key

sourceStore - the source store

sourceKey - the source key

atomicMove - true for an atomic move, false for a regular copy

Returns:

true if the file was found in the source store, false if it was not found

Throws:

IOException

copyOrMoveBlob

String copyOrMoveBlob(String key,
                      BlobStore sourceStore,
                      String sourceKey,
                      boolean atomicMove)
               throws IOException

Writes a file based on a key, as an optimized copy/move from a source in another compatible blob store.

The target key may be null, which is a signal from the caller that it has determined that deduplication is enabled and async digest computation is enabled, but the needed digest hasn't been computed, so this method should either find the digest in an efficient way if it can, or otherwise trigger an async digest computation.

If the copy/move is requested to be atomic, then the destination file is created atomically. In case of atomic move, in some stores the destination will be created atomically but the source will only be deleted afterwards.

The returned key may be different than the passed one when versioning is used.

Parameters:

key - the key; or null if the store should choose it or trigger async digest computation

sourceStore - the source store

sourceKey - the source key

atomicMove - true for an atomic move, false for a regular copy

Returns:

the key of the copied/moved file, or null if copy/move failed

Throws:

IOException

Since:

11.5

getFile

@NotNull
BlobStore.OptionalOrUnknown<Path> getFile(String key)

Gets an already-existing file containing the blob for the given key, if present.

Note that this method is best-effort, it may return unknown even though the blob exists in the store, it's just that it's not handily available locally in a file.

Parameters:

key - the blob key

Returns:

the file containing the blob, or empty if the blob cannot be found, or unknown if no file is available locally

getStream

@NotNull
BlobStore.OptionalOrUnknown<InputStream> getStream(String key)
                                            throws IOException

Gets the stream of the blob for the given key, if present.

Note that this method is best-effort, it may return unknown even though the blob exists in the store, it's just that it's not efficient to return it as a stream.

Parameters:

key - the blob key

Returns:

the blob stream, or empty if the blob cannot be found, or unknown if no stream is efficiently available

Throws:

IOException

readBlob

boolean readBlob(String key,
                 Path dest)
          throws IOException

Reads a blob based on its key into the given file.

Parameters:

key - the blob key

dest - the file to use to store the fetched data

Returns:

true if the file was fetched, false if the file was not found

Throws:

IOException

writeBlobProperties

void writeBlobProperties(BlobUpdateContext blobUpdateContext)
                  throws IOException

Sets properties on a blob.

Parameters:

blobUpdateContext - the blob update context

Throws:

IOException

deleteBlob

void deleteBlob(BlobContext blobContext)

Deletes a blob.

Parameters:

blobContext - the blob context

deleteBlob

void deleteBlob(String key)

Deletes a blob based on a key. No error occurs if the blob does not exist.

This method does not throw IOException, but may log an error message.

Parameters:

key - the blob key

exists

default boolean exists(String key)

Does a blob with the given key exist in the blob store.

The existence of the blob is checked in the store where the blob is effectively stored. Intermediate cache is ignored.

Parameters:

key - the blob key

Returns:

true if it exists in the blob store

Since:

2023

hasDefaultStorageClass

default boolean hasDefaultStorageClass(String key)

Does a blob with the given key exist in the blob store with the default storage class.

The existence of the blob is checked in the store where the blob is effectively stored. Intermediate cache is ignored. A blob with a cold storage storage class is not in default storage class and this method will return false for such a blob.

Parameters:

key - the blob key

Returns:

true if it exists in the blob store and has the default storage class

Since:

2023.5

getBinaryGarbageCollector

BinaryGarbageCollector getBinaryGarbageCollector()

Returns the binary garbage collector (GC).

Several calls to this method will return the same GC, so that its status can be monitored using BinaryGarbageCollector.isInProgress().

Returns:

the binary GC

unwrap

BlobStore unwrap()

If this blob store wraps another one, returns it, otherwise returns this.

Returns:

the lowest-level blob store

clear

void clear()

INTERNAL (TESTS). Clears the blob store of all its data.

Since:

11.5