Class DataHub

java.lang.Object

com.github.sttk.sabi.DataHub

All Implemented Interfaces:

DataAcc, AutoCloseable

public class DataHub
extends Object
implements DataAcc, AutoCloseable

Manages local data sources and data connections, and executes business logic in transactional or non-transactional scopes.

A DataHub acts as a container for local DataSrc instances and provides access to connections implementing DataConn. It supports executing logic functions through run(Logic) for non-transactional operations and txn(Logic) for transactional operations. In a transaction, connection commits, rollbacks, and failure reporting are handled automatically.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	DataHub.CreatedDataConnIsNull	Represents an error when a created data connection instance is null.
static final record	DataHub.FailToCastDataConn	Represents an error when a connection cannot be cast to the target connection type.
static final record	DataHub.FailToCastDataHub	Represents an error when casting this DataHub instance to the generic data context fails.
static final record	DataHub.FailToCreateDataConn	Represents an error when creating a data connection fails.
static final record	DataHub.FailToSetupGlobalDataSrcs	Represents an error when setting up global data sources fails.
static final record	DataHub.FailToSetupLocalDataSrcs	Represents an error when setting up local data sources fails.
static final record	DataHub.NoDataSrcToCreateDataConn	Represents an error when no data source with the specified name is found.
static final record	DataHub.RuntimeExceptionOccurred	Represents an error when an unhandled runtime exception occurs during logic execution.

Constructor Summary

Constructors

Constructor	Description
DataHub()	Constructs a new, default DataHub instance.
DataHub(String... names)	Constructs a new DataHub instance configured to use specified global data sources.
DataHub(List<String> names)	Constructs a new DataHub instance configured to use specified global data sources.

Method Summary

Modifier and Type	Method	Description
void	close()	Closes all local data sources registered in this hub and releases their resources.
void	disuses(String name)	Unregisters a local DataSrc associated with the given name from this hub.
<C extends DataConn> C	getDataConn(String name, Class<C> cls)	Retrieves a data connection associated with the specified data source name and casts it to the requested connection class type.
<D> void	run(Logic<D> logic)	Executes business logic in a non-transactional scope.
<D> void	txn(Logic<D> logic)	Executes business logic within a transactional boundary.
void	uses(String name, DataSrc ds)	Registers a local DataSrc with a specific name in this hub.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DataHub

public DataHub()

Constructs a new, default DataHub instance.

DataHub

public DataHub(List<String> names)

Constructs a new DataHub instance configured to use specified global data sources.

Parameters:

names - the list of global data source names to bind to this hub

DataHub

public DataHub(String... names)

Constructs a new DataHub instance configured to use specified global data sources.

Parameters:

names - varargs array of global data source names to bind to this hub

Method Details

uses

public void uses(String name,
 DataSrc ds)

Registers a local DataSrc with a specific name in this hub.

Parameters:

name - the logical name for the data source

ds - the DataSrc instance to register

disuses

public void disuses(String name)

Unregisters a local DataSrc associated with the given name from this hub.

Parameters:

name - the logical name of the data source to remove

close

public void close()

Closes all local data sources registered in this hub and releases their resources.

Specified by:

close in interface AutoCloseable

getDataConn

public <C extends DataConn> C getDataConn(String name,
 Class<C> cls)
                                   throws com.github.sttk.errs.Err

Retrieves a data connection associated with the specified data source name and casts it to the requested connection class type.

If a connection for the given name has already been created within the current transaction or execution scope, that connection instance is returned. Otherwise, a new connection is created via the corresponding registered data source.

Specified by:

getDataConn in interface DataAcc

Type Parameters:

C - the expected type of DataConn

Parameters:

name - the registered logical name of the data source

cls - the Class representing the target connection type C

Returns:

the data connection instance associated with the specified name

Throws:

com.github.sttk.errs.Err - if the data source is not found, connection creation fails or returns null, or casting to cls fails

run

public <D> void run(Logic<D> logic)
             throws com.github.sttk.errs.Err

Executes business logic in a non-transactional scope.

This method passes this hub instance (cast to type D) to Logic.run(Object). Connections acquired during execution are managed within the scope.

Type Parameters:

D - the type of data context expected by the logic, typically DataHub or a subclass/interface

Parameters:

logic - the business logic to execute

Throws:

com.github.sttk.errs.Err - if the logic throws Err, if casting to D fails (wrapping DataHub.FailToCastDataHub), or if an unhandled runtime exception occurs (wrapping DataHub.RuntimeExceptionOccurred)

txn

public <D> void txn(Logic<D> logic)
             throws com.github.sttk.errs.Err

Executes business logic within a transactional boundary.

Upon successful completion of Logic.run(Object), all acquired data connections are committed. If an exception occurs, all connections are automatically rolled back, transaction failure reports are dispatched to connections, and the exception is rethrown wrapped in Err.

Type Parameters:

D - the type of data context expected by the logic

Parameters:

logic - the business logic to execute transactionally

Throws:

com.github.sttk.errs.Err - if the logic throws Err, connection commit or rollback fails, casting to D fails, or a runtime exception occurs