Package de.ubs.xdm3.batch.modification

Class ModificationUtils

java.lang.Object
de.ubs.xdm3.batch.modification.ModificationUtils
All Implemented Interfaces:
Closeable, AutoCloseable
Direct Known Subclasses:
MappingTableUtils
public class ModificationUtils extends Object implements Closeable
This class offers functions to persist data in a database. It allows to store and retrieve data based on a key. The data can be stored in different tables. Each table can have a different key and data portion. The get and put methods are used to retrieve and put data into the respective table.
The first put operation to a specified table will internally create the table based on the provided data. This means that the key and data of the put is used to create a table in the background.

  • Field Details

  • Constructor Details

    • ModificationUtils

      @Deprecated public ModificationUtils()
      Deprecated.
      Constructs a new ModificationUtils object that uses an internal database that stores the data in the /xdm/data/modification directory.

    • ModificationUtils

      @Deprecated public ModificationUtils(String databaseName)
      Deprecated.
      Constructs a new ModificationUtils object that uses an internal H2 database that stores the data in the /xdm/data/<databaseName> directory.
      Parameters:
      databaseName - Name of the H2 database and of the directory.

    • ModificationUtils

      public ModificationUtils(String url, String user, String password)
      Constructs a new ModificationUtils object that uses a database with the provided properties. The data will be stored at the location that has been specified in the URL.
      Parameters:
      url - A jdbc url of a database. The url must start with jdbc:.
      user - A user to access the database.
      password - A password to access the database.

    • ModificationUtils

      public ModificationUtils(Connection connection) throws SQLException
      Constructs a new ModificationUtils object that uses the database with the specified connection.
      Parameters:
      connection - A connection to an external database.
      Throws:
      SQLException

  • Method Details

    • close

      public void close()
      This method closes all open resources of the ModificationUtils object. This includes prepared statements and open database connections. You should always call this method to ensure that all stored data is correctly persisted to the hard drive. This method also inserts pending rows that are still in the batch window cache.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • setBatchExecutionSize

      public void setBatchExecutionSize(int batchExecutionSize)
      Sets the internal batch size that is used to insert / update values. The implementation uses a value of 1000 by default. This setting controls how many insert/update statements are executed in one block by the database system.
      Parameters:
      batchExecutionSize - The size of the batch window.

    • getNextValueFor

      public long getNextValueFor(String sequenceName)
      Returns the next values for a created sequence and returns it to the caller. This method internally calls the statement CALL NEXT VALUE FOR .... The specified sequence must be created before with a CREATE SEQUENCE statement.
      Parameters:
      sequenceName - The name of the sequence for which the next value should be fetched.
      Returns:
      The next value returned by the sequence.

    • merge

      public void merge(String tableName, Object[] key, Object... data)
      Insert or update a row into the specified table of the internal database. The method ensures that the internal table will be created if it does not exist yet.
      Parameters:
      tableName - Specifies the table into which the data should be inserted. The table will be created if it does not exist yet and the create argument has been set to true.
      key - Specifies the key data under which the data is stored into the internal table. This key can be used to retrieve the data later with the get(String, Object...) method.
      data - A data array that is stored for the specific key. This data is returned by the get(String, Object...) method for the specified key.
      Throws:
      ModificationException - If the data could not be stored in the database, or the table could not be created.

    • merge

      public void merge(String tableName, Object[] key, Object[] data, boolean create)
      Insert or update a row into the specified table of the internal database.
      Parameters:
      tableName - Specifies the table into which the data should be inserted. The table will be created if it does not exist yet and the create argument has been set to true.
      key - Specifies the key data under which the data is stored into the internal table. This key can be used to retrieve the data later with the get(String, Object...) method.
      data - A data array that is stored for the specific key. This data is returned by the get(String, Object...) method for the specified key.
      create - Controls if the table should be created if it does not exist or not. If the table does not exist and the argument is false an exception will be thrown.
      Throws:
      ModificationException - If the data could not be stored in the database, or the table could not be created.

    • put

      public boolean put(String tableName, Object[] key, Object... data)
      Puts a new row into the specified table of the internal database. The method ensures that the internal table will be created if it does not exist yet.
      Parameters:
      tableName - Specifies the table into which the data should be inserted. The table will be created if it does not exist yet.
      key - Specifies the key data under which the data is stored into the internal table. This key can be used to retrieve the data later with the get(String, Object...) method.
      data - A data array that is stored for the specific key. This data is returned by the get(String, Object...) method for the specified key.
      Returns:
      True if a new entry was created and false if an existing entry was updated.
      Throws:
      ModificationException - If the data could not be stored in the database, or the table could not be created.

    • put

      public boolean put(String tableName, Object[] key, Object[] data, boolean create)
      Puts a new row into the specified table of the internal database.
      Parameters:
      tableName - Specifies the table into which the data should be inserted. The table will be created if it does not exist yet and the create argument has been set to true.
      key - Specifies the key data under which the data is stored into the internal table. This key can be used to retrieve the data later with the get(String, Object...) method.
      data - A data array that is stored for the specific key. This data is returned by the get(String, Object...) method for the specified key.
      create - Controls if the table should be created if it does not exist or not. If the table does not exist and the argument is false an exception will be thrown.
      Returns:
      True if a new entry was created and false if an existing entry was updated.
      Throws:
      ModificationException - If the data could not be stored in the database, or the table could not be created.

    • executeStatement

      public void executeStatement(String sql)
      Executes a SQL statement against the internal database. This method can be used to get more control/access to the internal database. Please take care that you don't drop existing tables, because all data of these will be lost.
      Parameters:
      sql - The SQL statement that should be executed against the database.
      Throws:
      ModificationException - If an error occurred while executing the statement.

    • drop

      public void drop(String tableName)
      Drops the table in the internal database if exists. This method will have no effect if the table does not exist. On the other hand if the table exists all data that has been stored in that table will be lost.
      Parameters:
      tableName - Specifies the table that should be dropped.
      Throws:
      ModificationException - If the table could not be dropped.

    • count

      public long count(String tableName)
      Returns the number of rows that have been currently stored in the specified table. This method will execute a SELECT COUNT(*) FROM tableName query each time the method is called. Please keep in mind that this might have been performance drawbacks if the method is called many times.
      Parameters:
      tableName - The table name for which the number of rows should be returned.
      Returns:
      The number of rows for the specified table.
      Throws:
      ModificationException - If the number of rows could not be determined.

    • count

      public Map<CompositeKey,Long> count(String tableName, String... columns)
      Returns the number of rows that have been currently stored in the specified table. This method will execute a SELECT COUNT(*) FROM tableName query each time the method is called. Please keep in mind that this might have been performance drawbacks if the method is called many times.
      Parameters:
      tableName - The table name for which the number of rows should be returned.
      columns - Optional list of columns. These columns are used to count the number of rows aggregated on these columns.
      Returns:
      The number of rows for each distinct key of the aggregated columns.
      Throws:
      ModificationException - If the number of rows could not be determined.

    • tableExists

      public boolean tableExists(String tableName) throws ModificationException
      Checks if a table with the given name tableName exists in the database.
      Parameters:
      tableName - Name of a table
      Returns:
      True if a table exists and false when the table is not existing
      Throws:
      ModificationException - If a database access error occurs.

    • get

      public Object[] get(String tableName, Object... key)
      Retrieves the data for the specified key from the specified table. The method will return null if there is no data with the specified key. Otherwise, an array is returned that contains the data that has been stored by the put(String, Object[], Object...) method.
      Parameters:
      tableName - Specifies the table name from which the data should be read.
      key - The key data for which a lookup in the internal table is performed.
      Returns:
      The data that is stored for the specified key. If the key or table does not exist in the database the method will return null.
      Throws:
      ModificationException - If an issue occurred while reading the data from the database.

    • hasKey

      public boolean hasKey(String tableName, Object[] key)
      Checks the existence of a dataset with the given key.
      Parameters:
      tableName - Specifies the table name
      key - The key data for which a lookup in the internal table is performed.
      Returns:
      True when the specified key exists and false otherwise