Module litebridge.orm
Package org.litebridgedb.orm

Class Litebridge

java.lang.Object
org.litebridgedb.orm.Litebridge
All Implemented Interfaces:
SelectApi
public final class Litebridge extends Object implements SelectApi
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 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.

    • Litebridge

      public Litebridge(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

    • Litebridge

      public Litebridge(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

    • Litebridge

      public Litebridge(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

    • Litebridge

      public Litebridge(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

    • Litebridge

      public Litebridge(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

    • Litebridge

      public Litebridge(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

  • Method Details

    • 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.

    • 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)
      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.

    • 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)
      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.

    • update

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

    • 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, @Nullable 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.
      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.
      Returns:
      A DtoFromClauseTerminal instance for querying and retrieving data for the specified DTO class.

    • select

      public FromClauseStart 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 FromClauseStart 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 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> void delete(Class<DTO> dtoClass, Function<DtoDeleteWhereClause<DTO>,DeleteQuery> 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 DtoDeleteWhereClause.

    • 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 void delete(String tableName, Function<SqlDeleteWhereClause,DeleteQuery> query)
      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
      query - a function that takes an instance of SqlDeleteWhereClause and returns a DeleteQuery, specifying the conditions for deleting the records

    • 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

    • 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)
      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.

      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