Package onl.ycode.stormify

Class StormifyManager

java.lang.Object
onl.ycode.stormify.StormifyManager
public class StormifyManager extends Object
The main controller for the Stormify system. It is the entrance point for all the operations on the database.

It is a singleton and r requires a data source to be set before any operations can be performed. The data source is required to be a generic JDBC data source.

The controller provides methods to perform queries, create, update, and delete entities, and execute stored procedures. It also provides methods to perform transactions and other database operations, like populating an entity, retrieving all details of a parent object, etc.

  • Method Details

    • stormify

      public static StormifyManager stormify()
      Returns the singleton instance of the controller.
      Returns:
      the singleton instance of the controller.

    • getDataSource

      public DataSource getDataSource()
      Returns the data source used by the controller. See setDataSource(DataSource).
      Returns:
      the data source used by the controller.

    • onInit

      public void onInit(Runnable runnable)
      Runs the given code block when the controller is initialized.
      Parameters:
      runnable - the code block to be run when the controller is initialized. More than one code blocks could be added.

    • isDataSourcePresent

      public boolean isDataSourcePresent()
      Checks if the data source is present in the controller.
      Returns:
      the data source used by the controller, or null if no data source is set.

    • setDataSource

      public void setDataSource(DataSource dataSource)
      Sets the data source to be used by the controller. You need to provide a generic JDBC data source, by any means necessary.

      The data source is required to be set before any operations can be performed.

      The data source cannot be null. To detach the data source from the controller, use closeDataSource() instead.

      Parameters:
      dataSource - the data source to be used by the controller. Can be null to detach the data source from StormifyManager.

    • closeDataSource

      public void closeDataSource()
      Closes the data source used by the controller. This method should be called when the controller is no longer needed. If no data source is set, a QueryException is thrown.

    • getLogger

      public onl.ycode.logger.Logger getLogger()
      Returns the logger used by the controller. See setLogger(Logger).
      Returns:
      the logger used by the controller.

    • setLogger

      public void setLogger(onl.ycode.logger.Logger logger)
      Sets the logger to be used by the controller. By default, the logger is LogManager.getLogger(String) with the name "Stormify".
      Parameters:
      logger - the logger to be used by the controller.

    • registerPrimaryKeyResolver

      public void registerPrimaryKeyResolver(int priority, BiPredicate<String,String> resolver)
      Registers a primary key resolver function that will be used to determine the primary key field name for a given table.
      Parameters:
      priority - the priority of the resolver. The higher the value, the higher the priority.
      resolver - the resolver function that takes the table name and the name of the current field as input and returns true if the field is a primary key.

    • setNamingPolicy

      public void setNamingPolicy(NamingPolicy namingPolicy)
      Sets the naming policy to be used by the controller. By default, the naming policy is NamingPolicy.lowerCaseWithUnderscores (snake_case). Note that the policy will only update the tables and fields that are not already registered.
      Parameters:
      namingPolicy - the naming policy to be used by the controller.

    • getNamingPolicy

      public NamingPolicy getNamingPolicy()
      Returns the naming policy used by the controller. See setNamingPolicy(NamingPolicy).
      Returns:
      the naming policy used by the controller.

    • executeUpdate

      public int executeUpdate(String query, Object... params)
      Executes a query and returns the number of rows affected. This call is expected to update the status of the database. It is used when SQL queries like INSERT, UPDATE, DELETE are executed.
      Parameters:
      query - the query to be executed.
      params - the parameters to be used in the query.
      Returns:
      the number of rows affected.

    • readCursor

      public <T> int readCursor(Class<T> baseClass, String query, Consumer<T> consumer, Object... params)
      Executes a read operation and returns the number of rows affected. Use this method when the strategy of parsing the result row by row is preferred, instead of fetching all the results at once. Thus, data are consumed as they are fetched from the database, making it ideal for large data sets.
      Type Parameters:
      T - the type of the results.
      Parameters:
      baseClass - the base class of the results.
      query - the query to be executed.
      consumer - the consumer to be used to process the results. Evey new row is passed to this consumer.
      params - the parameters to be used in the query.
      Returns:
      the number of rows affected.

    • read

      public <T> List<T> read(Class<T> baseClass, String query, Object... params)
      Executes a read operation and returns the list of results.
      Type Parameters:
      T - the type of the results.
      Parameters:
      baseClass - the base class of the results.
      query - the query to be executed.
      params - the parameters to be used in the query.
      Returns:
      the list of results. This list is never null.

    • readOne

      public <T> T readOne(Class<T> baseClass, String query, Object... params)
      Executes a read operation and returns a single result. If no results are found, null is returned. If multiple results are found, a QueryException is thrown.
      Type Parameters:
      T - the type of the result.
      Parameters:
      baseClass - the base class of the result.
      query - the query to be executed.
      params - the parameters to be used in the query.
      Returns:
      the single result. This result can be null if no data is found.

    • populate

      public <T> T populate(T entity)
      Populates the entity with the data from the database.
      Type Parameters:
      T - the type of the entity.
      Parameters:
      entity - the entity to be populated.
      Returns:
      the populated entity. This is the same entity that was passed as an argument.

    • getSqlDialect

      public SqlDialect getSqlDialect()
      Returns the SQL dialect used by the controller. See SqlDialect.
      Returns:
      the SQL dialect used by the controller.

    • create

      public <T> T create(T createdItem)
      Creates a new entity in the database.
      Type Parameters:
      T - the type of the entity.
      Parameters:
      createdItem - the entity to be created.
      Returns:
      the created entity.

    • update

      public <T> T update(T updatedItem)
      Updates an entity in the database.
      Type Parameters:
      T - the type of the entity.
      Parameters:
      updatedItem - the entity to be updated.
      Returns:
      the updated entity.

    • delete

      public <T> void delete(T deletedItem)
      Deletes an entity from the database.
      Type Parameters:
      T - the type of the entity.
      Parameters:
      deletedItem - the entity to be deleted.

    • transaction

      public void transaction(SafeRunnable block)
      Executes a transaction with the given block of code.
      Parameters:
      block - the block of code to be executed.

    • getDetails

      public <M, D> List<D> getDetails(M parent, Class<D> detailsClass)
      Returns the details of the parent object. This method assumes that the details object has only one property field that references the parent object. If more than one field references the parent object, or no
      Type Parameters:
      M - the type of the parent object.
      D - the type of the details.
      Parameters:
      parent - the parent object.
      detailsClass - the class of the details.
      Returns:
      the details of the parent object as a list.

    • getDetails

      public <M, D> List<D> getDetails(M parent, Class<D> detailsClass, String propertyName)
      Returns the details of the parent object.
      Type Parameters:
      M - the type of the parent object.
      D - the type of the details.
      Parameters:
      parent - the parent object.
      detailsClass - the class of the details.
      propertyName - the name of the reference property in the details class (i.e. the foreign key property name). If empty, the first field of the parent class that matches the details class will be used. If more than one field matches, an exception will be thrown.
      Returns:
      the details of the parent object as a list.

    • findAll

      public <T> List<T> findAll(Class<T> clazz, String whereClause, Object... arguments)
      Finds all the entities of the given class, while applying the given where clause.
      Type Parameters:
      T - the type of the entities.
      Parameters:
      clazz - the class of the entities.
      whereClause - the where clause to be applied. The clause can be empty or null. It should contain the WHERE keyword.
      arguments - the arguments to be used in the where clause, if the where clause exists.
      Returns:
      the list of entities.

    • findById

      public <T> T findById(Class<T> clazz, Object id)
      Finds the entity of the given class with the given ID.
      Type Parameters:
      T - the type of the entity.
      Parameters:
      clazz - the class of the entity.
      id - the ID of the entity.
      Returns:
      the entity with the given ID or null if not found.

    • getTableInfo

      public TableInfo getTableInfo(Class<?> clazz)
      Returns the table information for the given class. Use this data to retrieve information about the database representation of the class.
      Parameters:
      clazz - the class for which the table information is required.
      Returns:
      the table information for the given class.

    • storedProcedure

      public void storedProcedure(String name, SPParam<?>... params)
      Executes a stored procedure with the given name and parameters.
      Parameters:
      name - the name of the stored procedure.
      params - the parameters to be used in the stored procedure.

    • addBlacklistField

      public void addBlacklistField(String fieldName)
      Adds a field to the blacklist. The blacklist is used to prevent certain fields from being used as a column in the database.
      Parameters:
      fieldName - the name of the field to be added to the blacklist.

    • removeBlacklistField

      public void removeBlacklistField(String fieldName)
      Removes a field from the blacklist. The blacklist is used to prevent certain fields from being used as a column in the database.
      Parameters:
      fieldName - the name of the field to be removed from the blacklist.

    • isStrictMode

      public boolean isStrictMode()
      Set the object mapping to strict mode. In strict mode, the system will throw an exception if a field is not found in the entity. Otherwise, it will log a warning and continue.

      By default, the system is in strict mode.

      Returns:
      the current strict mode setting.

    • setStrictMode

      public void setStrictMode(boolean strictMode)
      Set the object mapping to strict mode. In strict mode, the system will throw an exception if a field is not found in the entity. Otherwise, it will log a warning and continue.

      By default, the system is in strict mode.

      Parameters:
      strictMode - the strict mode setting.