net.ofk.dbmapper.api.Storage Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dbmapper Show documentation
Provides access to data storage to run queries and to map results onto plain objects
The newest version!
package net.ofk.dbmapper.api;

import java.util.List;

/**
 * Provides access to a data storage,
 * allows to store, modify data or fetch them.
 * Basically, this is intended to be used with RDBM systems,
 * but in theory can be used with another types of data storages.
 *
 * R - type of the raw results as returned by the underlying data storage.
 */
public interface Storage {
  /**
   * Executes a query which stores new data.
   * The result should contain ids of the inserted entities.
   */
  List insert(String queryTemplate, Object... paramValues) throws Throwable;

  /**
   * Executes a query which updates existing entities.
   * The result is the amount of the affected entities.
   */
  int update(String queryTemplate, Object... paramValues) throws Throwable;

  /**
   * Returns a list of records.
   * Mapper will be responsible for creating elements of the list from the provided raw results.
   */
   List select(Mapper mapper, String queryTemplate, Object... paramValues) throws Throwable;

  /**
   * Returns a list of records.
   * The default mapper will create an object of the given @param type.
   */
   List select(Class type, String queryTemplate, Object... paramValues) throws Throwable;

  /**
   * Returns a list of records.
   * Every record will contain a list of field values.
   */
  List> select(String queryTemplate, Object... paramValues) throws Throwable;

  /**
   * An utility method which checks if the amount of updated records is not null.
   */
  void updateMany(int count);

  /**
   * An utility method which checks if exactly one record has been updated.
   */
  void updateOne(int count);

  /**
   * An utility method which checks if not more than one record has been updated.
   */
  void updateOneOrNone(int count);

  /**
   * Returns the provided list or throws an IllegalStateException
   * if the list has no values.
   */
   List takeMany(List list);

  /**
   * Returns the first element of the provided list
   * or throws an IllegalStateException
   * if the list has no values or has more than one value.
   */
   T takeOne(List list);

  /**
   * Returns the first element of the provided list
   * or throws an IllegalStateException if the list has more than one value.
   * Returns null if the list is empty.
   */
   T takeOneOrNone(List list);

  /**
   * Returns a list of elements which are the first elements of the inner lists.
   */
   List takeFirstColumn(List> list);

  /**
   * Alters a value so it can be used as a string value
   * in queries without breaking them, causing syntax errors or SQL-injections.
   */
  String escape(String value);

  interface Mapper {
    T map(R r) throws Throwable;
  }
}