@Immutable
public interface BinaryValue extends Comparable<BinaryValue>, Serializable, org.modeshape.jcr.api.Binary {

    /**
     * Get the length of this binary data.
     *
     * Note that this method, unlike the standard {@link javax.jcr.Binary#getSize()} method,
     * does not throw an exception.
     *
     * @return the number of bytes in this binary data
     */
    @Override
    public long getSize();

    /**
     * Get the key for the binary value.
     *
     * @return the key; never null
     */
    public BinaryKey getKey();
}

@ThreadSafe
public interface BinaryStore {
    /**
     * Initialize the store and get ready for use.
     */
    public void start();

    /**
     * Shuts down the store.
     */
    public void shutdown();

   /**
     * Get the minimum number of bytes that a binary value must contain before it can
     * be stored in the binary store.
     * @return the minimum number of bytes for a stored binary value; never negative
     */
    long getMinimumBinarySizeInBytes();

    /**
     * Set the minimum number of bytes that a binary value must contain before it can
     * be stored in the binary store.
     * @param minSizeInBytes the minimum number of bytes for a stored binary value; never negative
     */
    void setMinimumBinarySizeInBytes( long minSizeInBytes );

    /**
     * Set the text extractor that can be used for extracting text from binary content.
     * @param textExtractor the text extractor
     */
    void setTextExtractor( TextExtractor textExtractor );

    /**
     * Set the MIME type detector that can be used for determining the MIME type for binary content.
     * @param mimeTypeDetector the detector; never null
     */
    void setMimeTypeDetector( MimeTypeDetector mimeTypeDetector );

    /**
     * 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.
     *
     * @param stream the stream containing the binary content to be stored; may not be null
     * @return the binary value representing the stored binary value; never null
     * @throws BinaryStoreException if there is a problem storing the content
     */
    BinaryValue storeValue( InputStream stream ) throws BinaryStoreException;

    /**
     * Get an InputStream to the binary content with the supplied key.
     *
     * @param key the key to the binary content; never null
     * @return the input stream through which the content can be read
     * @throws BinaryStoreException if there is a problem reading the content from the store
     */
    InputStream getInputStream( BinaryKey key ) 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.
     *
     * Note that the implementation must *never* block.
     *
     * @param 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
     */
    void markAsUnused( Iterable<BinaryKey> keys ) throws BinaryStoreException;

    /**
     * Remove binary values that have been unused for at least the specified amount of time.
     *
     * Note that the implementation must *never* block.
     *
     * @param minimumAge the minimum time that a binary value has been unused before it can be
     *        removed; must be non-negative
     * @param unit the time unit for the minimum age; may not be null
     * @throws BinaryStoreException if there is a problem removing the unused values
     */
    void removeValuesUnusedLongerThan( long minimumAge,
                                       TimeUnit unit ) throws BinaryStoreException;

    /**
     * Get the text that can be extracted from this binary content.
     *
     * @param binary the binary content; may not be null
     * @return the extracted text, or null if none could be extracted
     * @throws BinaryStoreException if the binary content could not be accessed
     */
    String getText( BinaryValue binary ) throws BinaryStoreException;

    /**
     * Get the MIME type for this binary value.
     *
     * @param binary the binary content; may not be null
     * @param name the name of the content, useful for determining the MIME type;
     * may be null if not known
     * @return the MIME type, or null if it cannot be determined (e.g., the Binary is empty)
     * @throws IOException if there is a problem reading the binary content
     * @throws RepositoryException if an error occurs.
     */
    String getMimeType( BinaryValue binary,
                        String name ) throws IOException, RepositoryException;

    /**
     * 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 {@link BinaryKey}s only as the iterator is used.
     *
     * @return the iterable set of binary keys; never null
     * @throws BinaryStoreException if anything unexpected happens.
     */
    Iterable<BinaryKey> getAllBinaryKeys() throws BinaryStoreException;