Module sproket.github.io.persism
Package net.sf.persism

Class Session

java.lang.Object
net.sf.persism.Session
All Implemented Interfaces:
AutoCloseable
public final class Session extends Object implements AutoCloseable
Performs various read and write operations in the database.
Since:
1/8/2021
Author:
Dan Howard

  • Constructor Summary

    Constructors
    Constructor
    Description
    Session(Connection connection)
     
    Session(Connection connection, String sessionKey)
    Constructor for Session where you want to specify the Session Key.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close the connection
    int
    delete(Class<?> objectClass, Parameters primaryKeyValues)
    Deletes data from the database based on the specified primary keys provided
    int
    delete(Class<?> objectClass, SQL whereClause)
    Deletes data from the database based on the specified WHERE clause
    int
    delete(Class<?> objectClass, SQL whereClause, Parameters parameters)
    Deletes data from the database based on the specified WHERE clause and parameters
    <T> Result<T>
    delete(T object)
    Deletes the data object from the database.
    <T> T
    fetch(Class<T> objectClass, Parameters primaryKeyValues)
    Fetch object by primary key(s)
    <T> T
    fetch(Class<T> objectClass, SQL sql)
    Fetch object by arbitrary SQL
    <T> T
    fetch(Class<T> objectClass, SQL sql, Parameters parameters)
    Fetch an object of the specified type from the database.
    boolean
    fetch(Object object)
    Fetch an object from the database by it's primary key(s).
    <T> Result<T>
    insert(T object)
    Inserts the data object in the database refreshing with autoinc and other defaults that may exist.
    <T> List<T>
    query(Class<T> objectClass)
    Query to return all results.
    <T> List<T>
    query(Class<T> objectClass, Parameters primaryKeyValues)
    Query to return any results matching the primary key values provided.
    <T> List<T>
    query(Class<T> objectClass, SQL sql)
    Query for any arbitrary SQL statement.
    <T> List<T>
    query(Class<T> objectClass, SQL sql, Parameters parameters)
    Query for a list of objects of the specified class using the specified SQL query and parameters.
    <T> Result<T>
    update(T object)
    Updates the data object in the database.
    void
    withTransaction(Runnable transactionBlock)
    Function block of database operations to group together in one transaction.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Session

      public Session(Connection connection) throws PersismException
      Parameters:
      connection - db connection
      Throws:
      PersismException - if something goes wrong

    • Session

      public Session(Connection connection, String sessionKey) throws PersismException
      Constructor for Session where you want to specify the Session Key.
      Parameters:
      connection - db connection
      sessionKey - Unique string to represent the connection URL if it is not available on the Connection metadata. This string should start with the jdbc url string to indicate the connection type.

      jdbc:h2 = h2
      jdbc:sqlserver = MS SQL
      jdbc:oracle = Oracle
      jdbc:sqlite = SQLite
      jdbc:derby = Derby
      jdbc:mysql = MySQL/MariaDB
      jdbc:postgresql = PostgreSQL
      jdbc:firebirdsql = Firebird (Jaybird)
      jdbc:hsqldb = HSQLDB
      jdbc:ucanaccess = MS Access
      jdbc:informix = Informix
      Throws:
      PersismException - if something goes wrong

  • Method Details

    • close

      public void close()
      Close the connection
      Specified by:
      close in interface AutoCloseable

    • fetch

      public boolean fetch(Object object) throws PersismException
      Fetch an object from the database by it's primary key(s). You should instantiate the object and set the primary key properties before calling this method.
      Parameters:
      object - Data object to read from the database.
      Returns:
      true if the object was found by the primary key.
      Throws:
      PersismException - if something goes wrong.

    • fetch

      public <T> T fetch(Class<T> objectClass, Parameters primaryKeyValues)
      Fetch object by primary key(s)
      Type Parameters:
      T - Type
      Parameters:
      objectClass - Type to return (should be a POJO data class or a record)
      primaryKeyValues - primary key values
      Returns:
      Instance of object type T or NULL if not found
      Throws:
      PersismException - if you pass a Java primitive or other invalid type for objectClass or something else goes wrong.

    • fetch

      public <T> T fetch(Class<T> objectClass, SQL sql)
      Fetch object by arbitrary SQL
      Type Parameters:
      T - Type
      Parameters:
      objectClass - Type to return
      sql - SQL query
      Returns:
      Instance of object type T or NULL if not found
      Throws:
      PersismException - if something goes wrong.

    • fetch

      public <T> T fetch(Class<T> objectClass, SQL sql, Parameters parameters)
      Fetch an object of the specified type from the database. The type can be a Data Object or a native Java Object or primitive.
      Type Parameters:
      T - Return type
      Parameters:
      objectClass - Type of returned value
      sql - query - this would usually be a select OR a select of a single column if the type is a primitive. If this is a primitive type then this method will only look at the 1st column in the result.
      parameters - parameters to the query.
      Returns:
      value read from the database of type T or null if not found
      Throws:
      PersismException - Well, this is a runtime exception, so it actually could be anything really.

    • query

      public <T> List<T> query(Class<T> objectClass)
      Query to return all results.
      Type Parameters:
      T - Return type
      Parameters:
      objectClass - Type of returned value
      Returns:
      List of type T read from the database
      Throws:
      PersismException - Oof.

    • query

      public <T> List<T> query(Class<T> objectClass, SQL sql)
      Query for any arbitrary SQL statement.
      Type Parameters:
      T - Return type
      Parameters:
      objectClass - Type of returned value
      sql - SQL to use for Querying
      Returns:
      List of type T read from the database
      Throws:
      PersismException - He's dead Jim!

    • query

      public <T> List<T> query(Class<T> objectClass, Parameters primaryKeyValues)
      Query to return any results matching the primary key values provided.
      Type Parameters:
      T - Return type
      Parameters:
      objectClass - Type of returned value
      primaryKeyValues - Parameters containing primary key values
      Returns:
      List of type T read from the database of any rows matching the primary keys. If you pass multiple primaries this will use WHERE IN(?,?,?) to find them.
      Throws:
      PersismException - Oh no. Not again.

    • query

      public <T> List<T> query(Class<T> objectClass, SQL sql, Parameters parameters)
      Query for a list of objects of the specified class using the specified SQL query and parameters. The type of the list can be Data Objects or native Java Objects or primitives.
      Type Parameters:
      T - Return type
      Parameters:
      objectClass - class of objects to return.
      sql - query string to execute.
      parameters - parameters to the query.
      Returns:
      a list of objects of the specified class using the specified SQL query and parameters.
      Throws:
      PersismException - If something goes wrong you get a big stack trace.

    • update

      public <T> Result<T> update(T object) throws PersismException
      Updates the data object in the database.
      Parameters:
      object - data object to update.
      Returns:
      Result object containing rows changed (usually 1 to indicate rows changed via JDBC) and the data object itself which may have been changed.
      Throws:
      PersismException - Indicating the upcoming robot uprising.

    • insert

      public <T> Result<T> insert(T object) throws PersismException
      Inserts the data object in the database refreshing with autoinc and other defaults that may exist.
      Type Parameters:
      T - Type of the returning data object in Result.
      Parameters:
      object - the data object to insert.
      Returns:
      Result object containing rows changed (usually 1 to indicate rows changed via JDBC) and the data object itself which may have been changed by auto-inc or column defaults.
      Throws:
      PersismException - When planet of the apes starts happening.

    • delete

      public <T> Result<T> delete(T object) throws PersismException
      Deletes the data object from the database.
      Parameters:
      object - data object to delete
      Returns:
      Result with usually 1 to indicate rows changed via JDBC.
      Throws:
      PersismException - If you mistakenly pass a Class rather than a data object, or other SQL Exception.

    • delete

      public int delete(Class<?> objectClass, SQL whereClause)
      Deletes data from the database based on the specified WHERE clause
      Parameters:
      objectClass - class of data object where to delete from.
      whereClause - WHERE clause condition.
      Returns:
      int rows affected
      Throws:
      PersismException - If something goes wrong in the Db.

    • delete

      public int delete(Class<?> objectClass, Parameters primaryKeyValues)
      Deletes data from the database based on the specified primary keys provided
      Parameters:
      objectClass - class of data object where to delete from.
      primaryKeyValues - primary key values
      Returns:
      int rows affected
      Throws:
      PersismException - If something goes wrong in the Db OR if you accidentally call this with 0 parameters.

    • delete

      public int delete(Class<?> objectClass, SQL whereClause, Parameters parameters)
      Deletes data from the database based on the specified WHERE clause and parameters
      Parameters:
      objectClass - class of data object where to delete from.
      whereClause - WHERE clause condition.
      parameters - parameters for the WHERE clause
      Returns:
      int rows affected
      Throws:
      PersismException - If something goes wrong in the Db.

    • withTransaction

      public void withTransaction(Runnable transactionBlock)
      Function block of database operations to group together in one transaction. This method will set autocommit to false then execute the function, commit and set autocommit back to true. 
      
 session.withTransaction(() -> {
     Contact contact = getContactFromSomewhere();

     contact.setIdentity(randomUUID);
     session.insert(contact);

     contact.setContactName("Wilma Flintstone");

     session.update(contact);
     session.fetch(contact);
 });
      Parameters:
      transactionBlock - Block of operations expected to run as a single transaction.
      Throws:
      PersismException - in case of SQLException where the transaction is rolled back.