Module litebridge.orm
Package org.litebridgedb.orm

Class Litebridge

java.lang.Object
org.litebridgedb.orm.Litebridge
public class Litebridge extends Object
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.

  • Constructor Details

    • Litebridge

      public Litebridge(DatabaseProvider databaseProvider, DataSource dataSource)
      Constructs a Litebridge instance with the specified database provider.
      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.

    • Litebridge

      public Litebridge(DatabaseProvider databaseProvider, TransactionManager transactionManager)

    • Litebridge

      public Litebridge(DatabaseProvider databaseProvider, TransactionManager transactionManager, MethodHandles.Lookup lookup)

  • Method Details

    • register

      public void register(MethodHandles.Lookup lookup, Class<?> dtoClass, Function<RegistrationContext,RegistrationTableContext> rc)
      Registers a DTO class along with its associated table specification using the provided lookup and registration context.
      Parameters:
      lookup - An instance of MethodHandles.Lookup used to access caller-sensitive methods.
      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<?> dtoClass, Function<RegistrationContext,RegistrationTableContext> rc)
      Registers a DTO class along with its associated table specification using the provided lookup and registration context.

      This uses a local `MethodHandles.lookup()` to reflect the DTO and optional interfaces.

      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(DtoTableSpec dtoTableSpec)
      Register a Data Transfer Object (DTO) class with its corresponding table specification.

      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.

      It uses a local `MethodHandles.lookup()` to reflect the DTO and optional interfaces.

      Parameters:
      dtoTableSpec - DTO-to-table mapping details

    • register

      public void register(MethodHandles.Lookup lookup, DtoTableSpec dtoTableSpec)
      Register a Data Transfer Object (DTO) class with its corresponding table specification, using the provided lookup object to reflect the DTO and optional interfaces.

      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:
      lookup - Lookup object used for reflecting the DTO and optional interfaces.
      dtoTableSpec - 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.

    • save

      public void save(Object... dtos)
      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:
      dtos - the Data Transfer Object(s) to be saved in the database.
      Throws:
      IllegalStateException - if an error occurs during the save operation.

    • save

      public void save(Collection<Object> dtos)
      Saves a collection of Data Transfer Objects (DTOs) to the database.
      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.

    • insert

      public void insert(Object dto)
      Insert 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.

    • 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> void update(Class<DTO> dtoClass, Function<DtoUpdateStart<DTO>,UpdateQuery> update)

    • update

      public void update(String tableName, Function<SqlUpdateStart,UpdateQuery> query)

    • select

      public <DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass)
      Select a registered Data Transfer Object (DTO) type for database query operations.
      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 DtoSelector instance for querying and retrieving data for the specified DTO class.
      Throws:
      IllegalArgumentException - if the specified DTO class is not registered in the table registry.

    • select

      public <DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass, Class<?> contextDtoClass)

    • select

      public SqlFromClause select(String... columns)
      Query data from the database, without mapping results to Data Transfer Objects (DTOs).

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

      This method constructs a SqlFromClause for further query composition by specifying the columns to be included in the SELECT clause.

      Parameters:
      columns - An array of column names to be included in the SELECT statement. Each column name must be a valid, non-null string.
      Returns:
      A SqlFromClause instance allowing further refinement of the SQL query, such as specifying the table or additional clauses.

    • select

      public SqlFromClause select(Aliased... columns)
      Query data from the database, without mapping results to Data Transfer Objects (DTOs).

      Creates a SQL SELECT statement with the specified columns the source table is specified via a chained from() call.

      This method constructs a SqlFromClause to enable further query composition.

      Parameters:
      columns - An array of Aliased objects representing the columns to be part of the SELECT statement. Each column must have a valid name and may optionally include an alias.
      Returns:
      A SqlFromClause instance that allows further refinement of the query, such as specifying the table or additional clauses.

    • select

      public SqlFromClause select()
      Query data from the database, without mapping results to Data Transfer Object (DTOs).

      Creates a SQL SELECT statement with all columns. The source table is specified via a chained from() call. This method constructs a SqlFromClause to enable further query composition.

      Returns:
      A SqlFromClause instance that allows further refinement of the query, such as specifying the table or additional clauses.

    • delete

      public void delete(Object dto)

    • delete

      public <DTO> void delete(Class<DTO> dtoClass, Function<DtoDeleteWhereClause<DTO>,DeleteQuery> query)

    • delete

      public <DTO> void delete(Class<DTO> dtoClass)

    • delete

      public void delete(String tableName, Function<SqlDeleteWhereClause,DeleteQuery> query)

    • delete

      public void delete(String tableName)

    • toDto

      public <DTO> DTO toDto(Row row, Class<DTO> dtoClass)
      Convert a given 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.

    • entityDtoMapper

      public <DTO> EntityDtoMapper<DTO> entityDtoMapper(Class<DTO> dtoClass, List<DtoEntityMapping> dtoEntityMappings)

    • transaction

      public TransactionContext transaction()