- All Implemented Interfaces:
SelectApi
- Direct Known Subclasses:
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 Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionLitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource) Constructs a Litebridge instance with the specified database provider and data source.LitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource, @Nullable LitebridgeConfig litebridgeConfig) Constructs a Litebridge instance with the specified database provider and data source.LitebridgeCore(DatabaseProvider databaseProvider, DataSource dataSource, @Nullable LitebridgeConfig litebridgeConfig, MethodHandles.Lookup lookup) Constructs a Litebridge instance with the specified database provider and data source.LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager) Constructs a Litebridge instance with the specified database provider, transaction manager, and default method handle lookup.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.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.LitebridgeCore(DatabaseProvider databaseProvider, TransactionManager transactionManager, LitebridgeConfig litebridgeConfig) Constructs a Litebridge instance with the specified database provider, transaction manager, and default method handle lookup.protectedLitebridgeCore(LitebridgeCore other) Copy constructor. -
Method Summary
Modifier and TypeMethodDescriptionprotected LitebridgeContextCreates a new DTO-modeLitebridgeContext.protected LitebridgeContextCreates a newLitebridgeContextconfigured for the specified mode.protected LitebridgeContextCreates a new SQL-modeLitebridgeContext.protected DatabaseProviderProvides access to the database provider for this Litebridge instance.<DTO> voidDeletes the specified DTO type (all records) by providing its class as a parameter.<DTO> UpdateResultdelete(Class<DTO> dtoClass, Function<DtoDeleteStart<DTO>, DeleteTerminal> query) Deletes records from the database for the given DTO class based on the specified query.voidDeletes the specified data transfer object (DTO) using the underlying persistence layer.voidDeletes all entries from the specified table.delete(String tableName, Function<SqlDeleteStart, DeleteTerminal> delete) Deletes records from the specified table in the database based on the provided delete query.<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.insert(Class<?> dtoClass, Function<DtoInsertIntoStep, InsertValuesStep> insert) Executes an insert operation for the specified DTO class using the provided insert builder function.voidInserts the specified Data Transfer Object (DTO) into the database via a SQL INSERT statement.insert(String tableName, Function<SqlInsertIntoStep, InsertValuesStep> insert) Executes an insert operation on the specified table using the provided insert builder function.inspect()Provides access to entity/mapped DTO inspection utilities.protected MappingPlanCacheProvides access to the mapping plan cache.Provides access to execute native/raw SQL queries.voidRegisters annotated entity class(es).voidregister(Class<?> dtoClass, Function<RegistrationContext, RegistrationContextTerminal> rc) Registers a DTO class along with its associated table specification using the provided registration context function.voidregister(DtoTableSpec... dtoTableSpecs) Register a Data Transfer Object (DTO) class(es) with its corresponding table specification(s).voidSave the given Data Transfer Object (DTO) to the database, via a SQL INSERT or UPDATE statement.voidSaves a collection of Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.voidSaves an array of Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.voidSave the given Data Transfer Objects (DTOs) to the database, via a SQL INSERT or UPDATE statement.select()Query data from the database, without mapping results to Data Transfer Object (DTOs).select(boolean literal) <DTO> DtoFromClauseTerminal<DTO> Select a registered Data Transfer Object (DTO) type for database query operations.<DTO> DtoFromClauseTerminal<DTO> Select a contextually-registered Data Transfer Object (DTO) type for database query operations.<DTO> DtoFromClauseTerminal<DTO> select(Class<DTO> dtoClass, RelatedDtoStrategy relatedDtoStrategy) Select a registered Data Transfer Object (DTO) type for database query operations.Query data from the database, without mapping results to Data Transfer Objects (DTOs).select(ExpressionSpec... expressions) Query data from the database, without mapping results to Data Transfer Objects (DTOs).<T> FromClauseStartTypeOverride<T> select(TypeOverride<T> expression) Query data from the database, without mapping results to Data Transfer Objects (DTOs).<T extends Number>
FromClauseStartTypeOverride<T> select(T literal) protected TableRegistryProvides access to the ORM table registry for this Litebridge instance.<DTO> DTOConverts the specified result row into a Data Transfer Object (DTO) of the specified type.<DTO> List<DTO> Converts the specified result rows into a Data Transfer Objects (DTOs) of the specified type.<T> Ttrack(T dto) Initiate change tracking for the given Data Transfer Object (DTO).Provides access to the current transaction context.<DTO> UpdateResultupdate(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.voidUpdate the specified Data Transfer Object (DTO) in the database via a SQL UPDATE statement.update(String tableName, Function<SqlUpdateStart, UpdateQuery> update) Executes an update operation on the specified table using the provided query function.static LitebridgeBuilder<Litebridge> withDatabase(DatabaseProvider databaseProvider) Create a builder for default Litebridge instances.static <LB extends LitebridgeCore>
LitebridgeBuilder<LB> withDatabase(LitebridgeOverrideDatabaseProvider<LB> databaseProvider) Create a builder for new Litebridge instances.
-
Field Details
-
persistenceFacade
-
-
Constructor Details
-
LitebridgeCore
Constructs a Litebridge instance with the specified database provider and data source.It uses the default method handle lookup, and Litebridge's
DefaultTransactionManagerto 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
DefaultTransactionManagerto 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
DefaultTransactionManagerto 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 configurationlookup- the MethodHandles.Lookup instance used for method and field lookups during change tracking
-
LitebridgeCore
Constructs a Litebridge instance with the specified database provider, transaction manager, and default method handle lookup.- Parameters:
databaseProvider- the provider responsible for managing database connectionstransactionManager- 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 connectionstransactionManager- the manager responsible for handling database transactionslitebridgeConfig- 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 operationstransactionManager- the manager that handles transaction lifecycles and operationslookup- 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 operationstransactionManager- the manager that handles transaction lifecycles and operationslitebridgeConfig- global runtime configurationlookup- the MethodHandles.Lookup instance used for method and field lookups during change tracking
-
LitebridgeCore
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
LitebridgeBuilderwith 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
LitebridgeCodrereturned.- 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
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
Registers annotated entity class(es).The annotated entity must be annotated with
Tableand contain at least one field annotated withColumn,OneToManyorManyToMany.- Parameters:
entityClasses- the class(es) of the entity/entities to be registered.
-
register
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
Provides access to entity/mapped DTO inspection utilities.The returned
DtoInspectorinstance is used to check the persistence state of an entity/DTO.- Returns:
- Inspector class providing access to entity state metadata.
-
save
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
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
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
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
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
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 intoinsert- a function that specifies the columns and values to insert- Returns:
- the result of the insert operation
-
insert
Executes an insert operation on the specified table using the provided insert builder function.- Parameters:
tableName- the name of the table to insert intoinsert- a function that specifies the columns and values to insert- Returns:
- the result of the insert operation
-
update
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 providedDtoUpdateStart.- Returns:
- The result of the update operation
-
update
Executes an update operation on the specified table using the provided query function.- Parameters:
tableName- the name of the table to updateupdate- a function that defines the update query, transforming aSqlUpdateStartinstance into anUpdateQuery- Returns:
- The result of the update operation
-
select
Description copied from interface:SelectApiSelect a registered Data Transfer Object (DTO) type for database query operations.Shortcut method; equivalent to
select().from(dtoClass).- Specified by:
selectin interfaceSelectApi- 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
DtoFromClauseTerminalinstance 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:SelectApiSelect a registered Data Transfer Object (DTO) type for database query operations.Shortcut method; equivalent to
select().from(dtoClass, relatedDtoStrategy).- Specified by:
selectin interfaceSelectApi- 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
DtoFromClauseTerminalinstance for querying and retrieving data for the specified DTO class.
-
select
Description copied from interface:SelectApiSelect a contextually-registered Data Transfer Object (DTO) type for database query operations.Shortcut method; equivalent to
select().from(dtoClass, contextDtoClass).- Specified by:
selectin interfaceSelectApi- 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
DtoFromClauseTerminalinstance for querying and retrieving data for the specified DTO class.
-
select
Description copied from interface:SelectApiQuery 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
FromClauseStartTypeOverridefor further query composition by specifying the target DTO or table for the query.- Specified by:
selectin interfaceSelectApi- 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 chainedfrom()call. Each field/column name must be a valid, non-null string.- Returns:
- A
FromClauseStartTypeOverrideinstance allowing further refinement of the SQL query by specifying the target DTO or table.
-
select
-
select
-
select
Description copied from interface:SelectApiQuery 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
FromClauseStartTypeOverridefor further query composition by specifying the target DTO or table for the query.- Specified by:
selectin interfaceSelectApi- Parameters:
expressions- An array ofExpressionSpecobjects representing the expressions to be part of the SELECT statement.- Returns:
- A
FromClauseStartTypeOverrideinstance allowing further refinement of the SQL query by specifying the target DTO or table.
-
select
Description copied from interface:SelectApiQuery 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
FromClauseStartTypeOverridefor further query composition by specifying the target DTO or table for the query.- Specified by:
selectin interfaceSelectApi- Type Parameters:
T- The return type of the query- Parameters:
expression- Return type-overriding expression- Returns:
- A
FromClauseStartTypeOverrideinstance allowing further refinement of the SQL query by specifying the target DTO or table.
-
select
Description copied from interface:SelectApiQuery 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
FromClauseStartTypeOverridefor further query composition by specifying the target DTO or table for the query.- Specified by:
selectin interfaceSelectApi- Returns:
- A
FromClauseStartTypeOverrideinstance allowing further refinement of the SQL query by specifying the target DTO or table.
-
delete
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 aDtoDeleteStart.- Returns:
- the result of the delete operation
-
delete
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
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 deleteddelete- a function that takes an instance ofSqlDeleteWhereClauseand returns aDeleteQuery, specifying the conditions for deleting the records- Returns:
- the result of the delete operation
-
delete
Deletes all entries from the specified table.- Parameters:
tableName- the name of the table from which to delete entries
-
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
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
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 handledtoEntityMappings- 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
Provides access to the current transaction context.Use this method to start a transaction.
- Returns:
- the current TransactionContext instance associated with this object
-
mappingPlanCache
Provides access to the mapping plan cache.- Returns:
- the
MappingPlanCacheinstance associated with this Litebridge instance
-
tableRegistry
Provides access to the ORM table registry for this Litebridge instance.- Returns:
- The
TableRegistryinstance associated with this Litebridge instance.
-
databaseProvider
Provides access to the database provider for this Litebridge instance.- Returns:
- The
DatabaseProviderinstance associated with this Litebridge instance.
-
createDtoLitebridgeContext
Creates a new DTO-modeLitebridgeContext.- Returns:
- a new DTO-mode Litebridge context
-
createSqlLitebridgeContext
Creates a new SQL-modeLitebridgeContext.- Returns:
- a new SQL-mode Litebridge context
-
createLitebridgeContext
Creates a newLitebridgeContextconfigured for the specified mode.- Parameters:
mode- the context mode (DTO or SQL)- Returns:
- a new Litebridge context
-