org.modeshape.jcr.value.binary
Interface BinaryStore

All Known Implementing Classes:

AbstractBinaryStore, DatabaseBinaryStore, FileSystemBinaryStore, InfinispanBinaryStore, MongodbBinaryStore, TransientBinaryStore

@ThreadSafe
public interface BinaryStore

The basic interface for a store for Binary value objects. All binary values that are of a minimum threshold size are stored in the store; smaller binary values are kept in-memory and are stored within the nodes.

Method Summary

Iterable<BinaryKey>	getAllBinaryKeys() Obtain an iterable implementation containing all of the store's binary keys.
InputStream	getInputStream(BinaryKey key) Get an InputStream to the binary content with the supplied key.
String	getMimeType(BinaryValue binary, String name) Get the MIME type for this binary value, never null.
long	getMinimumBinarySizeInBytes() Get the minimum number of bytes that a binary value must contain before it can be stored in the binary store.
String	getText(BinaryValue binary) Get the text that can be extracted from this binary content.
void	markAsUnused(Iterable<BinaryKey> keys) Mark the supplied binary keys as unused, but key them in quarantine until needed again (at which point they're removed from quarantine) or until removeValuesUnusedLongerThan(long, TimeUnit) is called.
void	removeValuesUnusedLongerThan(long minimumAge, TimeUnit unit) Remove binary values that have been unused for at least the specified amount of time.
void	setMimeTypeDetector(MimeTypeDetector mimeTypeDetector) Set the MIME type detector that can be used for determining the MIME type for binary content.
void	setMinimumBinarySizeInBytes(long minSizeInBytes) Set the minimum number of bytes that a binary value must contain before it can be stored in the binary store.
void	setTextExtractors(TextExtractors textExtractors) Set the text extractor that can be used for extracting text from binary content.
BinaryValue	storeValue(InputStream stream) Store the binary value and return the JCR representation.

Method Detail

getMinimumBinarySizeInBytes

long getMinimumBinarySizeInBytes()

Get the minimum number of bytes that a binary value must contain before it can be stored in the binary store.

Returns:

the minimum number of bytes for a stored binary value; never negative

setMinimumBinarySizeInBytes

void setMinimumBinarySizeInBytes(long minSizeInBytes)

Set the minimum number of bytes that a binary value must contain before it can be stored in the binary store.

Parameters:

minSizeInBytes - the minimum number of bytes for a stored binary value; may not be negative

setTextExtractors

void setTextExtractors(TextExtractors textExtractors)

Set the text extractor that can be used for extracting text from binary content.

Parameters:

textExtractors - a non-null TextExtractors instance

setMimeTypeDetector

void setMimeTypeDetector(MimeTypeDetector mimeTypeDetector)

Set the MIME type detector that can be used for determining the MIME type for binary content.

Parameters:

mimeTypeDetector - the detector

storeValue

BinaryValue storeValue(InputStream stream)
                       throws BinaryStoreException

Store the binary value and return the JCR representation. Note that if the binary content in the supplied stream is already persisted in the store, the store may simply return the binary value referencing the existing content.

Parameters:

stream - the stream containing the binary content to be stored; may not be null

Returns:

the binary value representing the stored binary value; never null

Throws:

BinaryStoreException - if there any unexpected problem

getInputStream

InputStream getInputStream(BinaryKey key)
                           throws BinaryStoreException

Get an InputStream to the binary content with the supplied key.

Parameters:

key - the key to the binary content; never null

Returns:

the input stream through which the content can be read, never null

Throws:

BinaryStoreException - if there is a problem reading the content from the store or if a valid, non-null InputStream cannot be returned for the given key.

markAsUnused

void markAsUnused(Iterable<BinaryKey> keys)
                  throws BinaryStoreException

Mark the supplied binary keys as unused, but key them in quarantine until needed again (at which point they're removed from quarantine) or until removeValuesUnusedLongerThan(long, TimeUnit) is called. This method ignores any keys for values not stored within this store.

Parameters:

keys - the keys for the binary values that are no longer needed

Throws:

BinaryStoreException - if there is a problem marking any of the supplied binary values as unused

removeValuesUnusedLongerThan

void removeValuesUnusedLongerThan(long minimumAge,
                                  TimeUnit unit)
                                  throws BinaryStoreException

Remove binary values that have been unused for at least the specified amount of time.

Parameters:

minimumAge - the minimum time that a binary value has been unused before it can be removed; must be non-negative

unit - the time unit for the minimum age; may not be null

Throws:

BinaryStoreException - if there is a problem removing the unused values

getText

String getText(BinaryValue binary)
               throws BinaryStoreException

Get the text that can be extracted from this binary content. If text extraction isn't enabled (either full text search is not enabled or there aren't any configured extractors), this returns null

If extraction is enabled, this method may block until a text extractor has finished extracting the text.

If there are any problems either with the binary value or during the extraction process, the exception will be logged and null is returned

In general, the implementation from AbstractBinaryStore should be enough and any custom BinaryStore implementations aren't expected to implement this.

Parameters:

binary - the binary content; may not be null

Returns:

the extracted text, or null if none could be extracted

Throws:

BinaryStoreException - if the binary content could not be accessed or if the given binary value cannot be found within the store.

getMimeType

String getMimeType(BinaryValue binary,
                   String name)
                   throws IOException,
                          RepositoryException

Get the MIME type for this binary value, never null.

If the store has never determined the mime-type of the given binary and the binary can be located in the store, it will attempt to determine it via the configured detectors and store it.

Parameters:

binary - the binary content; may not be null

name - the name of the content, useful for determining the MIME type; may be null if not known

Returns:

the MIME type of the content, as determined by the installed detectors or null if none of the detectors can determine it.

Throws:

IOException - if there is a problem reading the binary content

BinaryStoreException - if the binary value cannot be found in the store

RepositoryException - if any other error occurs.

getAllBinaryKeys

Iterable<BinaryKey> getAllBinaryKeys()
                                     throws BinaryStoreException

Obtain an iterable implementation containing all of the store's binary keys. The resulting iterator may be lazy, in the sense that it may determine additional BinaryKeys only as the iterator is used.

Returns:

the iterable set of binary keys; never null

Throws:

BinaryStoreException - if anything unexpected happens.