Class LitebridgeCore

java.lang.Object
org.litebridge.orm.LitebridgeCore
All Implemented Interfaces:
SelectApi
Direct Known Subclasses:
Litebridge

public class LitebridgeCore extends Object implements SelectApi
Basic primary entry point for Litebridge.

Litebridge is responsible for managing database interactions, including mapping Data Transfer Objects (DTOs) to tables, registering tables, change tracking, and executing query operations.

It provides a mechanism to translate between DTOs and database tables, facilitating CRUD operations while maintaining consistency and integrity.

Litebridge ensures thread safety by using immutable internal structures and leveraging the DatabaseProvider and PersistenceFacade for database interactions, ensuring that operations are performed safely and efficiently.

This class does not support SQL MERGE INTO operations.

See Also:
  • Field Details

  • Constructor Details

    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource)
      Constructs a Litebridge instance with the specified database provider and data source.

      It uses the default method handle lookup, and Litebridge's DefaultTransactionManager to manage transactions.

      Parameters:
      databaseProvider - the database provider to be used by Litebridge. This parameter is required to set up database operations and facilitate persistence functionalities. Must not be null.
      dataSource - the data source to be used by Litebridge. This parameter is required to provide database connectivity and facilitate persistence operations. Must not be null.
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource, @Nullable LitebridgeConfig litebridgeConfig)
      Constructs a Litebridge instance with the specified database provider and data source.

      It uses the default method handle lookup, and Litebridge's DefaultTransactionManager to manage transactions.

      Parameters:
      databaseProvider - the database provider to be used by Litebridge. This parameter is required to set up database operations and facilitate persistence functionalities. Must not be null.
      dataSource - the data source to be used by Litebridge. This parameter is required to provide database connectivity and facilitate persistence operations. Must not be null.
      litebridgeConfig - global runtime configuration
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource, @Nullable LitebridgeConfig litebridgeConfig, MethodHandles.Lookup lookup)
      Constructs a Litebridge instance with the specified database provider and data source.

      It uses Litebridge's DefaultTransactionManager to manage transactions.

      Parameters:
      databaseProvider - the database provider to be used by Litebridge. This parameter is required to set up database operations and facilitate persistence functionalities. Must not be null.
      dataSource - the data source to be used by Litebridge. This parameter is required to provide database connectivity and facilitate persistence operations. Must not be null.
      litebridgeConfig - global runtime configuration
      lookup - the MethodHandles.Lookup instance used for method and field lookups during change tracking
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager)
      Constructs a Litebridge instance with the specified database provider, transaction manager, and default method handle lookup.
      Parameters:
      databaseProvider - the provider responsible for managing database connections
      transactionManager - the manager responsible for handling database transactions
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager, LitebridgeConfig litebridgeConfig)
      Constructs a Litebridge instance with the specified database provider, transaction manager, and default method handle lookup.
      Parameters:
      databaseProvider - the provider responsible for managing database connections
      transactionManager - the manager responsible for handling database transactions
      litebridgeConfig - global runtime configuration
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager, MethodHandles.Lookup lookup)
      Constructs an instance of Litebridge, responsible for managing database operations, transaction contexts, change tracking, and persistence functionality.
      Parameters:
      databaseProvider - the provider responsible for supplying database connections and operations
      transactionManager - the manager that handles transaction lifecycles and operations
      lookup - the MethodHandles.Lookup instance used for method and field lookups during change tracking
    • LitebridgeCore

      public LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager, @Nullable LitebridgeConfig litebridgeConfig, MethodHandles.Lookup lookup)
      Constructs an instance of Litebridge, responsible for managing database operations, transaction contexts, change tracking, and persistence functionality.
      Parameters:
      databaseProvider - the provider responsible for supplying database connections and operations
      transactionManager - the manager that handles transaction lifecycles and operations
      litebridgeConfig - global runtime configuration
      lookup - the MethodHandles.Lookup instance used for method and field lookups during change tracking
    • LitebridgeCore

      protected LitebridgeCore(LitebridgeCore other)
      Copy constructor.
      Parameters:
      other - Instance to copy.
  • Method Details

    • withDatabase

      public static <LB extends LitebridgeCore> LitebridgeBuilder<LB> withDatabase(LitebridgeOverrideDatabaseProvider<LB> databaseProvider)
      Create a builder for new Litebridge instances.

      Returns a new instance of LitebridgeBuilder with the specified database provider and data source.

      Crucially, this allows the database provider to dynamically alter the available Litebridge APIs by determining the subclass/implementation of LitebridgeCodre returned.

      Type Parameters:
      LB - the type of LitebridgeCore
      Parameters:
      databaseProvider - the provider managing database interactions
      Returns:
      a new instance of LitebridgeBuilder configured with the provided database provider and data source
    • withDatabase

      public static LitebridgeBuilder<Litebridge> withDatabase(DatabaseProvider databaseProvider)
      Create a builder for default Litebridge instances.
      Parameters:
      databaseProvider - the provider managing database interactions
      Returns:
      a new instance of LitebridgeBuilder configured with the provided database provider and data source
    • register

      public void register(Class<?> dtoClass, Function<RegistrationContext,RegistrationContextTerminal> rc)
      Registers a DTO class along with its associated table specification using the provided registration context function.
      Parameters:
      dtoClass - The class object of the DTO (Data Transfer Object) to be registered.
      rc - A function that takes a RegistrationContext instance to configure the table mapping.
    • register

      public void register(Class<?>... entityClasses)
      Registers annotated entity class(es).

      The annotated entity must be annotated with Table and contain at least one field annotated with Column, OneToMany or ManyToMany.

      Parameters:
      entityClasses - the class(es) of the entity/entities to be registered.
    • register

      public void register(DtoTableSpec... dtoTableSpecs)
      Register a Data Transfer Object (DTO) class(es) with its corresponding table specification(s).

      This method maps the DTO class to a database table and stores the association in the table registry to enable database operations such as insert, update, or query.

      Parameters:
      dtoTableSpecs - One or more DTO-to-table mapping details
    • track

      public <T> T track(T dto)
      Initiate change tracking for the given Data Transfer Object (DTO).

      This process involves associating the DTO with its corresponding ORM table and enabling change tracking for the object's fields.

      Type Parameters:
      T - the type of the Data Transfer Object being tracked.
      Parameters:
      dto - the Data Transfer Object to be tracked; must not be null and must be registered with a corresponding table.
      Returns:
      the tracked Data Transfer Object.
      Throws:
      IllegalArgumentException - if the DTO is null or if its class is not registered.
    • inspect

      public DtoInspector inspect()
      Provides access to entity/mapped DTO inspection utilities.

      The returned DtoInspector instance is used to check the persistence state of an entity/DTO.

      Returns:
      Inspector class providing access to entity state metadata.
    • save

      public void save(Object dto)
      Save the given Data Transfer Object (DTO) to the database, via a SQL INSERT or UPDATE statement.

      This method utilises the persistence facade to perform the save operation. It handles SQL exceptions and ensures the integrity of the save process.

      Parameters:
      dto - the Data Transfer Object(s) to be saved in the database.
      Throws:
      IllegalStateException - if an error occurs during the save operation.
    • saveAll

      public void saveAll(Iterable<?> dtos)
      Saves a collection of Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.
      Parameters:
      dtos - a collection of objects to save in the database; must not be null.
      Throws:
      IllegalStateException - if an error occurs during the save operation.
    • saveAll

      public void saveAll(Object[] dtos)
      Saves an array of Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.
      Parameters:
      dtos - an array of objects to save in the database; must not be null.
      Throws:
      IllegalStateException - if an error occurs during the save operation.
    • saveAll

      public void saveAll(Object dto, Object... otherDtos)
      Save the given Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.
      Parameters:
      dto - first Data Transfer Object to be saved in the database.
      otherDtos - additional Data Transfer Objects to be saved in the database.
      Throws:
      IllegalStateException - if an error occurs during the save operation.`
    • insert

      public void insert(Object dto)
      Inserts the specified Data Transfer Object (DTO) into the database via a SQL INSERT statement.

      This method uses the persistence facade to perform the insertion and handles any SQL exceptions that might occur during the process.

      Parameters:
      dto - the Data Transfer Object to be inserted into the database. It must correspond to a properly configured and valid DTO.
      Throws:
      IllegalStateException - if an error occurs during the insertion process.
    • insert

      public InsertResult insert(Class<?> dtoClass, Function<DtoInsertIntoStep,InsertValuesStep> insert)
      Executes an insert operation for the specified DTO class using the provided insert builder function.
      Parameters:
      dtoClass - the DTO class representing the table to insert into
      insert - a function that specifies the columns and values to insert
      Returns:
      the result of the insert operation
    • insert

      public InsertResult insert(String tableName, Function<SqlInsertIntoStep,InsertValuesStep> insert)
      Executes an insert operation on the specified table using the provided insert builder function.
      Parameters:
      tableName - the name of the table to insert into
      insert - a function that specifies the columns and values to insert
      Returns:
      the result of the insert operation
    • update

      public void update(Object dto)
      Update the specified Data Transfer Object (DTO) in the database via a SQL UPDATE statement.

      This method utilises the persistence facade to perform the update operation and handles any SQL exceptions that might occur during the process.

      Parameters:
      dto - the Data Transfer Object to be updated in the database. It must represent a valid and properly tracked DTO.
      Throws:
      IllegalStateException - if an error occurs while performing the update.
    • update

      public <DTO> UpdateResult update(Class<DTO> dtoClass, Function<DtoUpdateStart<DTO>,UpdateQuery> update)
      Updates the data in the database for the given DTO class by applying the specified update query.
      Type Parameters:
      DTO - The type of the Data Transfer Object (DTO) to be updated.
      Parameters:
      dtoClass - The class of the DTO that determines the table to be updated.
      update - A function that builds the update query using the provided DtoUpdateStart.
      Returns:
      The result of the update operation
    • update

      public UpdateResult update(String tableName, Function<SqlUpdateStart,UpdateQuery> update)
      Executes an update operation on the specified table using the provided query function.
      Parameters:
      tableName - the name of the table to update
      update - a function that defines the update query, transforming a SqlUpdateStart instance into an UpdateQuery
      Returns:
      The result of the update operation
    • select

      public <DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass)
      Description copied from interface: SelectApi
      Select a registered Data Transfer Object (DTO) type for database query operations.

      Shortcut method; equivalent to select().from(dtoClass).

      Specified by:
      select in interface SelectApi
      Type Parameters:
      DTO - The type of the DTO to select.
      Parameters:
      dtoClass - The class of the DTO to be queried, which must already be registered.
      Returns:
      A DtoFromClauseTerminal instance for querying and retrieving data for the specified DTO class.
    • select

      public <DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass, RelatedDtoStrategy relatedDtoStrategy)
      Description copied from interface: SelectApi
      Select a registered Data Transfer Object (DTO) type for database query operations.

      Shortcut method; equivalent to select().from(dtoClass, relatedDtoStrategy).

      Specified by:
      select in interface SelectApi
      Type Parameters:
      DTO - The type of the DTO to select.
      Parameters:
      dtoClass - The class of the DTO to be queried, which must already be registered.
      relatedDtoStrategy - The strategy to use for fetching related DTOs.
      Returns:
      A DtoFromClauseTerminal instance for querying and retrieving data for the specified DTO class.
    • select

      public <DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass, Class<?> contextDtoClass)
      Description copied from interface: SelectApi
      Select a contextually-registered Data Transfer Object (DTO) type for database query operations.

      Shortcut method; equivalent to select().from(dtoClass, contextDtoClass).

      Specified by:
      select in interface SelectApi
      Type Parameters:
      DTO - The type of the DTO to select.
      Parameters:
      dtoClass - The class of the DTO to be queried, which must already be registered.
      contextDtoClass - The context DTO class for determining the table mapping.
      Returns:
      A DtoFromClauseTerminal instance for querying and retrieving data for the specified DTO class.
    • select

      public FromClauseStart<Row> select(String... fieldsOrColumns)
      Description copied from interface: SelectApi
      Query data from the database, without mapping results to Data Transfer Objects (DTOs).

      Creates a SQL SELECT statement with the specified fields/expressions; the source table is specified via a chained from() call.

      This method constructs a FromClauseStartTypeOverride for further query composition by specifying the target DTO or table for the query.

      Specified by:
      select in interface SelectApi
      Parameters:
      fieldsOrColumns - An array of field/column names to be included in the SELECT statement, dependent on whether a DTO or raw SQL is selected in the chained from() call. Each field/column name must be a valid, non-null string.
      Returns:
      A FromClauseStartTypeOverride instance allowing further refinement of the SQL query by specifying the target DTO or table.
    • select

      public <T extends Number> FromClauseStartTypeOverride<T> select(T literal)
      Specified by:
      select in interface SelectApi
    • select

      public FromClauseStartTypeOverride<Boolean> select(boolean literal)
      Specified by:
      select in interface SelectApi
    • select

      public FromClauseStart<Row> select(ExpressionSpec... expressions)
      Description copied from interface: SelectApi
      Query data from the database, without mapping results to Data Transfer Objects (DTOs).

      Creates a SQL SELECT statement with the specified fields/expressions; the source table is specified via a chained from() call.

      This method constructs a FromClauseStartTypeOverride for further query composition by specifying the target DTO or table for the query.

      Specified by:
      select in interface SelectApi
      Parameters:
      expressions - An array of ExpressionSpec objects representing the expressions to be part of the SELECT statement.
      Returns:
      A FromClauseStartTypeOverride instance allowing further refinement of the SQL query by specifying the target DTO or table.
    • select

      public <T> FromClauseStartTypeOverride<T> select(TypeOverride<T> expression)
      Description copied from interface: SelectApi
      Query data from the database, without mapping results to Data Transfer Objects (DTOs).

      Creates a SQL SELECT statement with the specified fields/expressions; the source table is specified via a chained from() call.

      This method constructs a FromClauseStartTypeOverride for further query composition by specifying the target DTO or table for the query.

      Specified by:
      select in interface SelectApi
      Type Parameters:
      T - The return type of the query
      Parameters:
      expression - Return type-overriding expression
      Returns:
      A FromClauseStartTypeOverride instance allowing further refinement of the SQL query by specifying the target DTO or table.
    • select

      public FromClauseStart<Row> select()
      Description copied from interface: SelectApi
      Query data from the database, without mapping results to Data Transfer Object (DTOs).

      Creates a SQL SELECT statement with all fields/expressions. The source table is specified via a chained from() call.

      This method constructs a FromClauseStartTypeOverride for further query composition by specifying the target DTO or table for the query.

      Specified by:
      select in interface SelectApi
      Returns:
      A FromClauseStartTypeOverride instance allowing further refinement of the SQL query by specifying the target DTO or table.
    • delete

      public void delete(Object dto)
      Deletes the specified data transfer object (DTO) using the underlying persistence layer.
      Parameters:
      dto - the data transfer object to be deleted; must not be null
      Throws:
      IllegalStateException - if the deletion process fails due to a database error
    • delete

      public <DTO> UpdateResult delete(Class<DTO> dtoClass, Function<DtoDeleteStart<DTO>,DeleteTerminal> query)
      Deletes records from the database for the given DTO class based on the specified query.
      Type Parameters:
      DTO - The type of the Data Transfer Object (DTO) representing the table.
      Parameters:
      dtoClass - The class of the DTO to identify the table for deletion.
      query - A function that builds the delete query using a DtoDeleteStart.
      Returns:
      the result of the delete operation
    • delete

      public <DTO> void delete(Class<DTO> dtoClass)
      Deletes the specified DTO type (all records) by providing its class as a parameter.
      Type Parameters:
      DTO - The type of the Data Transfer Object to be deleted.
      Parameters:
      dtoClass - The class type of the DTO that is to be deleted.
    • delete

      public UpdateResult delete(String tableName, Function<SqlDeleteStart,DeleteTerminal> delete)
      Deletes records from the specified table in the database based on the provided delete query.
      Parameters:
      tableName - the name of the table from which records will be deleted
      delete - a function that takes an instance of SqlDeleteWhereClause and returns a DeleteQuery, specifying the conditions for deleting the records
      Returns:
      the result of the delete operation
    • delete

      public void delete(String tableName)
      Deletes all entries from the specified table.
      Parameters:
      tableName - the name of the table from which to delete entries
    • nativeSql

      public NativeSqlContext nativeSql()
      Provides access to execute native/raw SQL queries.

      These types of queries/statements bypass most of the ORM layers and returns the low-level result.

      Returns:
      the native SQL execution API
    • toDto

      public <DTO> DTO toDto(Row row, Class<DTO> dtoClass)
      Converts the specified result row into a Data Transfer Object (DTO) of the specified type.
      Type Parameters:
      DTO - The type of the Data Transfer Object to be created.
      Parameters:
      row - The data row to map, containing column-value pairs. Must not be null.
      dtoClass - The class type of the DTO to which the row is to be mapped. Must not be null.
      Returns:
      An instance of the specified DTO type, populated with values from the given row.
      Throws:
      IllegalArgumentException - if the row or dtoClass is null, or if mapping fails due to type mismatches or invalid configurations.
      See Also:
    • toDtos

      public <DTO> List<DTO> toDtos(List<Row> rows, Class<DTO> dtoClass)
      Converts the specified result rows into a Data Transfer Objects (DTOs) of the specified type.
      Type Parameters:
      DTO - The type of the Data Transfer Objects to be created.
      Parameters:
      rows - The data rows to map, containing column-value pairs. Must not be null.
      dtoClass - The class type of the DTO to which the row is to be mapped. Must not be null.
      Returns:
      An instance of the specified DTO type, populated with values from the given row.
      Throws:
      IllegalArgumentException - if the row or dtoClass is null, or if mapping fails due to type mismatches or invalid configurations.
      See Also:
    • entityDtoMapper

      public <DTO> EntityDtoMapper<DTO> entityDtoMapper(Class<DTO> dtoClass, List<DtoEntityMapping> dtoEntityMappings)
      Creates an instance of EntityDtoMapper for the specified DTO class and entity-to-DTO mappings.

      This allows raw row results to be mapped to DTO instances.

      Type Parameters:
      DTO - the type of the DTO
      Parameters:
      dtoClass - the class of the DTO that the mapper will handle
      dtoEntityMappings - the list of mappings between DTO fields and corresponding entity fields
      Returns:
      an instance of EntityDtoMapper configured for the specified DTO class and mappings
    • transaction

      public TransactionContext transaction()
      Provides access to the current transaction context.

      Use this method to start a transaction.

      Returns:
      the current TransactionContext instance associated with this object
    • mappingPlanCache

      protected MappingPlanCache mappingPlanCache()
      Provides access to the mapping plan cache.
      Returns:
      the MappingPlanCache instance associated with this Litebridge instance
    • tableRegistry

      protected TableRegistry tableRegistry()
      Provides access to the ORM table registry for this Litebridge instance.
      Returns:
      The TableRegistry instance associated with this Litebridge instance.
    • databaseProvider

      protected DatabaseProvider databaseProvider()
      Provides access to the database provider for this Litebridge instance.
      Returns:
      The DatabaseProvider instance associated with this Litebridge instance.
    • createDtoLitebridgeContext

      protected LitebridgeContext createDtoLitebridgeContext()
      Creates a new DTO-mode LitebridgeContext.
      Returns:
      a new DTO-mode Litebridge context
    • createSqlLitebridgeContext

      protected LitebridgeContext createSqlLitebridgeContext()
      Creates a new SQL-mode LitebridgeContext.
      Returns:
      a new SQL-mode Litebridge context
    • createLitebridgeContext

      protected LitebridgeContext createLitebridgeContext(LitebridgeContext.Mode mode)
      Creates a new LitebridgeContext configured for the specified mode.
      Parameters:
      mode - the context mode (DTO or SQL)
      Returns:
      a new Litebridge context