org.modeshape.jcr.value.binary

## Class DatabaseBinaryStore

- java.lang.Object
- - org.modeshape.jcr.value.binary.AbstractBinaryStore
  - - org.modeshape.jcr.value.binary.DatabaseBinaryStore

- All Implemented Interfaces:
    BinaryStore

      @ThreadSafe
      public class DatabaseBinaryStore
      extends AbstractBinaryStore

  A `BinaryStore` implementation that uses a database for persisting binary values.

  This binary store implementation establishes a connection to the specified database and then attempts to determine which type of database is being used. ModeShape is aware of the following database types:

  - `mysql`
  - `postgres`
  - `derby`
  - `hsql`
  - `h2`
  - `sqlite`
  - `db2`
  - `db2_390`
  - `informix`
  - `interbase`
  - `firebird`
  - `sqlserver`
  - `access`
  - `oracle`
  - `sybase`
  This binary store implementation then uses DDL and DML statements to create the table(s) if not already existing and to perform the various operations required of a binary store. ModeShape can use database-specific statements, although a default set of SQL-99 statements are used as a fallback.

  These statements are read from a property file named "`binary_store_{type}_database.properties`", where where " `{type}`" is one of the above-mentioned database type strings. These properties files are expected to be found on the classpath directly under "org/modeshape/jcr/database". If the corresponding file is not found on the classpath, then the " `binary_store_default_database.properties`" file provided by ModeShape is used.

  ModeShape provides out-of-the-box database-specific files for several of the DBMSes that are popular within the open source community. The properties files for the other database types are not provided (though the ModeShape community will gladly incorporate them if you wish to make them available to us); in such cases, simply copy one of the provided properties files (e.g., "`binary_store_default_database.properties`" is often a good start) and customize it for your particular DBMS, naming it according to the pattern described above and including it on the classpath.

  Note that this mechanism can also be used to override the statements that ModeShape does provide out-of-the-box. In such cases, be sure to place the file on the classpath before the ModeShape JARs so that your file will be discovered first.

  The JDBC driver used needs to be at least JDBC 1.4 (JDK 6) compliant, because `PreparedStatement.setBinaryStream(int parameterIndex, java.io.InputStream x)` is being used.

- - ### Field Summary

    - ### Fields inherited from class org.modeshape.jcr.value.binary.AbstractBinaryStore

      `logger, MEDIUM_BUFFER_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DatabaseBinaryStore(String datasourceJNDILocation)` Create new store that uses the JDBC DataSource in the given JNDI location.
    `DatabaseBinaryStore(String driverClass, String connectionURL, String username, String password)` Create new store.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Database` | `database()`
    `Iterable<BinaryKey>` | `getAllBinaryKeys()` Obtain an iterable implementation containing all of the store's binary keys of those binaries that are in use.
    `String` | `getExtractedText(BinaryValue source)` Returns the extracted text of a binary value, or `null` if such text hasn't been stored previously (but the binary value can be found in the store)
    `InputStream` | `getInputStream(BinaryKey key)` Get an `InputStream` to the binary content with the supplied key.
    `protected String` | `getStoredMimeType(BinaryValue source)` Returns the stored mime-type of a binary value.
    `void` | `markAsUnused(Iterable<BinaryKey> keys)` Mark the supplied binary keys as unused, but keep them in quarantine until needed again (at which point they're removed from quarantine) or until `BinaryStore.removeValuesUnusedLongerThan(long, TimeUnit)` is called.
    `void` | `markAsUsed(Iterable<BinaryKey> keys)` Marks the binary with supplied keys as used.
    `void` | `removeValuesUnusedLongerThan(long minimumAge, TimeUnit unit)` Remove binary values that have been `unused` for at least the specified amount of time.
    `void` | `shutdown()` Shuts down the store.
    `void` | `start()` Initialize the store and get ready for use.
    `void` | `storeExtractedText(BinaryValue source, String extractedText)` Stores the extracted text of a binary value into this store.
    `protected void` | `storeMimeType(BinaryValue source, String mimeType)` Stores the given mime-type for a binary value.
    `BinaryValue` | `storeValue(InputStream stream, boolean markAsUnused)` Store the binary value and return the JCR representation.

    - ### Methods inherited from class org.modeshape.jcr.value.binary.AbstractBinaryStore

      `bestBufferSize, detector, extractors, getMimeType, getMinimumBinarySizeInBytes, getText, hasBinary, setMimeTypeDetector, setMinimumBinarySizeInBytes, setTextExtractors, storeValue`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DatabaseBinaryStore

          public DatabaseBinaryStore(String driverClass,
                             String connectionURL,
                             String username,
                             String password)

      Create new store.
      Parameters:
        `driverClass` - JDBC driver class name
        `connectionURL` - database location
        `username` - database user name
        `password` - database password

    - #### DatabaseBinaryStore

          public DatabaseBinaryStore(String datasourceJNDILocation)

      Create new store that uses the JDBC DataSource in the given JNDI location.
      Parameters:
        `datasourceJNDILocation` - the JNDI name of the JDBC Data Source that should be used, or null

  - ### Method Detail

    - #### start

          public void start()

      Description copied from interface: `BinaryStore`
      Initialize the store and get ready for use.
      Specified by:
        `start` in interface `BinaryStore`
      Overrides:
        `start` in class `AbstractBinaryStore`

    - #### database

          protected Database database()

    - #### storeValue

          public BinaryValue storeValue(InputStream stream,
                               boolean markAsUnused)
                                 throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      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
        `markAsUnused` - a `boolean` which indicates if the binary will be stored as unused or not. Binaries used from normal sessions (via properties) will normally be stored as unused and they will be marked as used only on tx commit.
      Returns:
        the binary value representing the stored binary value; never null
      Throws:
        `BinaryStoreException` - if there any unexpected problem

    - #### getInputStream

          public InputStream getInputStream(BinaryKey key)
                                     throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      Get an `InputStream` to the binary content with the supplied key. The input stream will be returned as long as the binary value has not been removed, so expired binary values should be included here as well.
      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.

    - #### markAsUsed

          public void markAsUsed(Iterable<BinaryKey> keys)
                          throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      Marks the binary with supplied keys as used. This method should ignore any keys which are not present in the store.
      Parameters:
        `keys` - a `BinaryKey` `Iterable`, may not be null
      Throws:
        `BinaryStoreException` - if anything unexpected fails.

    - #### markAsUnused

          public void markAsUnused(Iterable<BinaryKey> keys)
                            throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      Mark the supplied binary keys as unused, but keep them in quarantine until needed again (at which point they're removed from quarantine) or until `BinaryStore.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

          public void removeValuesUnusedLongerThan(long minimumAge,
                                          TimeUnit unit)
                                            throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      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

    - #### getStoredMimeType

          protected String getStoredMimeType(BinaryValue source)
                                      throws BinaryStoreException

      Description copied from class: `AbstractBinaryStore`
      Returns the stored mime-type of a binary value.
      Specified by:
        `getStoredMimeType` in class `AbstractBinaryStore`
      Parameters:
        `source` - a `non-null` `BinaryValue`
      Returns:
        either a non-empty `String` if a stored mimetype exists, or `null` if such a value doesn't exist yet.
      Throws:
        `BinaryStoreException` - if there's a problem accessing the binary store or if the binary value cannot be found in the store

    - #### storeMimeType

          protected void storeMimeType(BinaryValue source,
                           String mimeType)
                                throws BinaryStoreException

      Description copied from class: `AbstractBinaryStore`
      Stores the given mime-type for a binary value.
      Specified by:
        `storeMimeType` in class `AbstractBinaryStore`
      Parameters:
        `source` - a `non-null` `BinaryValue`
        `mimeType` - a non-empty `String`
      Throws:
        `BinaryStoreException` - if there's a problem accessing the binary store

    - #### getExtractedText

          public String getExtractedText(BinaryValue source)
                                  throws BinaryStoreException

      Description copied from class: `AbstractBinaryStore`
      Returns the extracted text of a binary value, or `null` if such text hasn't been stored previously (but the binary value can be found in the store)
      Specified by:
        `getExtractedText` in class `AbstractBinaryStore`
      Parameters:
        `source` - a `non-null` `BinaryValue` instance from which the text was extracted
      Returns:
        a `String` representing the extracted text, or `null` if such text hasn't been stored in this store previously.
      Throws:
        `BinaryStoreException` - if the binary value cannot be found in the store.

    - #### storeExtractedText

          public void storeExtractedText(BinaryValue source,
                                String extractedText)
                                  throws BinaryStoreException

      Description copied from class: `AbstractBinaryStore`
      Stores the extracted text of a binary value into this store.
      Specified by:
        `storeExtractedText` in class `AbstractBinaryStore`
      Parameters:
        `source` - a `non-null` `BinaryValue` instance from which the text was extracted
        `extractedText` - a `non-null` and `non-blank` string representing the extracted text
      Throws:
        `BinaryStoreException` - if the operation fails or if the extracted text cannot be stored for the given binary value (regardless of the reason)

    - #### getAllBinaryKeys

          public Iterable<BinaryKey> getAllBinaryKeys()
                                               throws BinaryStoreException

      Description copied from interface: `BinaryStore`
      Obtain an iterable implementation containing all of the store's binary keys of those binaries that are in use. The resulting iterator may be lazy, in the sense that it may determine additional `BinaryKey`s only as the iterator is used.
      Returns:
        the iterable set of binary keys; never null
      Throws:
        `BinaryStoreException` - if anything unexpected happens.

    - #### shutdown

          public void shutdown()

      Description copied from interface: `BinaryStore`
      Shuts down the store.
      Specified by:
        `shutdown` in interface `BinaryStore`
      Overrides:
        `shutdown` in class `AbstractBinaryStore`

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.