Package dev.brachtendorf.jimagehash.matcher.persistent.database

Class H2DatabaseImageMatcher

  • All Implemented Interfaces:
    Serializable, AutoCloseable
    public class H2DatabaseImageMatcher
extends DatabaseImageMatcher
    A naive database based image matcher implementation. Images indexed by this matcher will be added to the database and retrieved if an image match is queried.

    This class is backed by the h2 database engine

    The image matcher supports chaining multiple hashing steps which will be invoked in the order the algorithms were added. Once a hashing algorithm fails to match a specific image the image is discarded pruning the search tree quickly.

    Opposed to the ConsecutiveMatcher this matcher does not stores a reference to the image data itself but just keeps track of the hash and the url of the image file. Additionally if hashing algorithms are added after images have been hashed the images will not be found without reindexing the image in question..

    Multiple database image matchers may use the same database in which case hashes created by the same hashing algorithm will be used in both matchers. 

     
 
 DatabaseImageMatcher matcher0, matcher1; 
 
 matcher0.addHashingAlgorithm(new AverageHash(32),...,...)
 matcher1.addHashingAlgorithm(new AverageHash(32),...,...)
 
 matcher0.addHashingAlgorithm(new AverageHash(24),...,...)

 matcher0.addImage(Image1)
    Starting from this point matcher1 would also be able to match against Image1. Be aware that this relationship isn't symmetric. Images added by calling matcher1.addImage(..) method will be matched at the first step in matcher0 but fail to find a hash for AverageHash(24) therefore discarding the image as a possible match.

    If this behaviour is not desired simply choose a different database for each image matcher.

    2 + n Tables are generated to save vales:

    1. ImageHasher(id,serialize): Allows to serialize an image matcher to the database
    2. HashingAlgos(id,keyLenght): Saves the bit resolution of each hashing algorithm
    3. ... n a table for each hashing algorithm used in an image matcher

    For each and every match the hashes have to be read from the database. This allows to persistently stores hashes but might not be as efficient as the ConsecutiveMatcher. Optimizations may include to store 0 or 1 level hashes (hashes created by the first invoked hashing algorithms at a memory level and only retrieve the later hashes from the database.

    Since:
    2.0.2 added, 3.0.0 extract h2 database image matcher into it's own class
    Author:
    Kilian
    See Also:
    Serialized Form

    • Constructor Detail

      • H2DatabaseImageMatcher

        public H2DatabaseImageMatcher​(String subname,
                              String user,
                              String password)
                       throws SQLException
        Attempts to establish a connection to the given database URL using the h2 database driver. If the database does not yet exist an empty db will be initialized.
        Parameters:
        subname - the database file name. By default the file looks at the base directory of the user.

        "jdbc:h2:~/" + subname

        user - the database user on whose behalf the connection is being made
        password - the user's password. May be empty
        Throws:
        SQLException - if an error occurs while connecting to the database or the h2 driver could not be found in the classpath
        SQLTimeoutException - when the driver has determined that the timeout value specified by the setLoginTimeout method has been exceeded and has at least tried to cancel the current database connection attempt
        Since:
        3.0.0

      • H2DatabaseImageMatcher

        public H2DatabaseImageMatcher​(Connection dbConnection)
                       throws SQLException
        Attempts to establish a connection to the given database using the supplied connection object. If the database does not yet exist an empty db will be initialized.
        Parameters:
        dbConnection - the database connection
        Throws:
        SQLException - if a database access error occurs null
        SQLTimeoutException - when the driver has determined that the timeout value specified by the setLoginTimeout method has been exceeded and has at least tried to cancel the current database connection attempt
        IllegalArgumentException - if the supplied dbConnection is not an h2 connection object

    • Method Detail

      • getFromDatabase

        public static H2DatabaseImageMatcher getFromDatabase​(String subname,
                                                     String user,
                                                     String password,
                                                     int id)
                                              throws SQLException
        Get a database image matcher which previously got serialized by calling DatabaseImageMatcher.serializeToDatabase(int) on the object.
        Parameters:
        subname - the database file name. By default the file looks at the base directory of the user.

        "jdbc:h2:~/" + subname

        user - the database user on whose behalf the connection is being made.
        password - the user's password. May be empty
        id - the id supplied to the serializeDatabase call
        Returns:
        the image matcher found in the database or null if not present
        Throws:
        SQLException - if an error occurs while connecting to the database or the h2 driver could not be found in the classpath
        Since:
        3.0.0

      • deleteDatabase

        public void deleteDatabase()
                    throws SQLException
        Drop all data in the tables and delete the database files. This method currently only supports h2 databases. After this method terminates successfully all further method calls of this object will throw an SQLException if applicable.

        Calling this method will close() all database connections. Therefore calling close() on this object is not necessary.

        Throws:
        SQLException - if an SQL error occurs
        Since:
        3.0.0