acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding

class documentation

class PostgreSQLBinding(DBBinding):

PostgreSQLBinding class.

Method	`addBatchNotification`	Add a batch notification to the database.
Method	`addOriginator`	Add an originator to the database.
Method	`backupDB`	Backup the database to a directory.
Method	`closeDB`	Close the database.
Method	`configure`	Configure the PostgreSQLBinding with the provided configuration.
Method	`countBatchNotifications`	Return the number of batch notifications for a resource and notification URI.
Method	`countResources`	Return the number of resources in the database.
Method	`createTables`	Create the necessary schema and tables if they do not exist.
Method	`deleteIdentifier`	Delete an identifier from the identifiers DB.
Method	`deleteRequests`	Remnove all stored requests from the database.
Method	`deleteResource`	Delete a resource from the database.
Method	`discoverResourcesByFilter`	Search for resources by a filter function. This goes through all resources in the database and applies the filter function to each resource. If the filter function returns True, the resource is added to the result list.
Method	`getActionRep`	Get an action representation by resource ID.
Method	`getAllActionReprs`	Return all action representations.
Method	`getBatchNotifications`	Return the batch notifications for a resource and notification URI.
Method	`getOriginator`	Get an originator and its information from the database.
Method	`getRequests`	Get requests for a resource ID, or all requests.
Method	`getSchedule`	Get a schedule from the database.
Method	`getSchedules`	Get all schedules from the database.
Method	`hasResource`	Check if a resource exists in the database.
Method	`insertRequest`	Add a request to the requests database.
Method	`insertResource`	Insert a resource into the database.
Method	`prepareStatements`	Prepare the PreparedStatements for various SQL operations.
Method	`purgeDB`	Purge the database. Remove all data
Method	`purgeStatistics`	Purge the statistics DB.
Method	`removeActionRepr`	Remove an action representation.
Method	`removeBatchNotifications`	Remove the batch notifications for a resource and notification URI.
Method	`removeChildResource`	Remove a child resource from the childResources DB.
Method	`removeOldRequests`	Remove old requests from the database.
Method	`removeOriginator`	Remove an originator from the database.
Method	`removeSchedule`	Remove a schedule from the database.
Method	`removeSubscriptionRepr`	Remove a subscription representation from the database.
Method	`searchActionsReprsForSubject`	Search for action representations by subject.
Method	`searchByFragment`	Search and return all resources that match the given dictionary/document.
Method	`searchChildResourceIDsByParentRIAndType`	Search for child resources by parent resource ID and optional type.
Method	`searchIdentifiers`	Search for an resource ID OR for a structured name in the identifiers DB.
Method	`searchResources`	Search for resources by structured resource name, resource ID, CSE-ID, parent resource ID, resource type, or application entity ID.
Method	`searchSchedulesForParent`	Search for schedules in the database.
Method	`searchStatistics`	Search for statistics.
Method	`searchSubscriptionReprs`	Search for subscription representations by resource ID or parent resource ID.
Method	`start`	Start the PostgreSQLBinding.
Method	`updateActionRepr`	Update an action representation.
Method	`updateResource`	Update a resource in the database. Only the fields that are not None will be updated.
Method	`upgradeTables`	Upgrade the tables if necessary.
Method	`upsertActionRepr`	Update or insert an action representation.
Method	`upsertChildResource`	Add a child resource to the childResources DB.
Method	`upsertIdentifier`	Insert or update an identifier into the identifiers DB and a structured resource name into the structuredResourceNames DB.
Method	`upsertResource`	Update or insert a resource into the database.
Method	`upsertSchedule`	Add or update a schedule in the database.
Method	`upsertStatistics`	Update or insert statistics.
Method	`upsertSubscriptionRepr`	Update or insert a subscription representation into the database.
Method	`validate`	Validate the configuration for the PostgreSQLBinding.
Class Variable	`tableActions`	The name of the table for actions.
Class Variable	`tableBatchNotifications`	The name of the table for batch notifications.
Class Variable	`tableChildResources`	The name of the table for child resource mappings.
Class Variable	`tableIdentidiers`	The name of the table for identifier mappings.
Class Variable	`tableOriginators`	The name of the table for originators.
Class Variable	`tableRequests`	The name of the table to store requests and responses.
Class Variable	`tableResources`	The name of the table for resources.
Class Variable	`tableSchedules`	The name of the table for schedules.
Class Variable	`tableStatistics`	The name of the table for statistic information.
Class Variable	`tableSubscriptions`	The name of the table for subscription mappings.
Instance Variable	`dbConnection`	The database connection object.
Instance Variable	`dbDatabase`	The name of the database to connect to.
Instance Variable	`dbHost`	The hostname of the database server.
Instance Variable	`dbPassword`	The password to connect to the database.
Instance Variable	`dbPort`	The port of the database server.
Instance Variable	`dbSchema`	The schema to use in the database.
Instance Variable	`dbUser`	The username to connect to the database.
Method	`_checkOpenConnection`	Check if the database connection is open.
Method	`_executePrepared`	Execute a prepared statement.
Method	`_fetchAllRows`	Fetch the first elements from all rows from the database cursor.
Method	`_fetchNumber`	Fetch one number from the database cursor.
Method	`_fetchSingleRow`	Fetch the first element from the first row from the database cursor.

def addBatchNotification(self, batchRecord: JSON) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.addBatchNotification

Add a batch notification to the database.

Parameters
batchRecord:`JSON`	The batch notification to add.

Returns
`bool`	True if the batch notification was added, False otherwise.

def addOriginator(self, originatorStructure: JSON, originator: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.addOriginator

Add an originator to the database.

Parameters
originatorStructure:`JSON`	The originator structure to add.
originator:`str`	The originator to add.

Returns
`bool`	Boolean value to indicate success or failure.

def backupDB(self, dir: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.backupDB

Backup the database to a directory.

Parameters
dir:`str`	The directory to backup to.

Returns
`bool`	Boolean value to indicate success or failure.

def closeDB(self): ¶

overrides acme.runtime.DBBinding.DBBinding.closeDB

Close the database.

@configure

def configure(self, config: Configuration): ¶

Configure the PostgreSQLBinding with the provided configuration.

Parameters
config:`Configuration`	The configuration object containing the settings for the PostgreSQLBinding.

def countBatchNotifications(self, ri: str, nu: str) -> int: ¶

overrides acme.runtime.DBBinding.DBBinding.countBatchNotifications

Return the number of batch notifications for a resource and notification URI.

Parameters
ri:`str`	The resource ID of the resource.
nu:`str`	The notification URI.

Returns
`int`	The number of batch notifications for the resource and notification URI.

def countResources(self) -> int: ¶

overrides acme.runtime.DBBinding.DBBinding.countResources

Return the number of resources in the database.

Returns
`int`	The number of resources in the database.

def createTables(self): ¶

Create the necessary schema and tables if they do not exist.

def deleteIdentifier(self, ri: str, srn: str): ¶

overrides acme.runtime.DBBinding.DBBinding.deleteIdentifier

Delete an identifier from the identifiers DB.

Parameters
ri:`str`	The resource ID of the resource.
srn:`str`	The structured resource name of the resource.

def deleteRequests(self, ri: str | None = None): ¶

overrides acme.runtime.DBBinding.DBBinding.deleteRequests

Remnove all stored requests from the database.

Parameters
ri:`str \| None`	Optional resouce ID. Only requests for this resource ID will be deleted.

def deleteResource(self, ri: str): ¶

overrides acme.runtime.DBBinding.DBBinding.deleteResource

Delete a resource from the database.

Parameters
ri:`str`	The resource ID of the resource.

def discoverResourcesByFilter(self, func: Callable[[JSON], bool]) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.discoverResourcesByFilter

Search for resources by a filter function. This goes through all resources in the database and applies the filter function to each resource. If the filter function returns True, the resource is added to the result list.

Parameters
func:`Callable[[JSON], bool]`	The filter function to use.

Returns
`list[JSON]`	A list of found resource documents, or an empty list.

def getActionRep(self, ri: str) -> JSON | None: ¶

overrides acme.runtime.DBBinding.DBBinding.getActionRep

Get an action representation by resource ID.

Parameters
ri:`str`	The resource ID of the action representation.

Returns
`JSON \| None`	The action representation, or None if not found.

def getAllActionReprs(self) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.getAllActionReprs

Return all action representations.

Returns
`list[JSON]`	A list of action representations, or None if not found.

def getBatchNotifications(self, ri: str, nu: str) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.getBatchNotifications

Return the batch notifications for a resource and notification URI.

Parameters
ri:`str`	The resource ID of the resource.
nu:`str`	The notification URI.

Returns
`list[JSON]`	A list of batch notifications for the resource and notification URI.

def getOriginator(self, originator: str) -> tuple[str, OriginatorType] | None: ¶

overrides acme.runtime.DBBinding.DBBinding.getOriginator

Get an originator and its information from the database.

Parameters
originator:`str`	The originator to search for.

Returns
`tuple[str, OriginatorType] \| None`	Tuple containing the originator and its type, or None if not found.

def getRequests(self, ri: str | None = None) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.getRequests

Get requests for a resource ID, or all requests.

Parameters
ri:`str \| None`	The target resource's resource ID. If None or empty, then all requests are returned

Returns
`list[JSON]`	List of Documents. May be empty.

def getSchedule(self, ri: str) -> JSON | None: ¶

overrides acme.runtime.DBBinding.DBBinding.getSchedule

Get a schedule from the database.

Parameters
ri:`str`	The resource ID of the schedule.

Returns
`JSON \| None`	The schedule, or None if not found.

def getSchedules(self) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.getSchedules

Get all schedules from the database.

Returns
`list[JSON]`	List of Documents. May be empty.

def hasResource(self, ri: str | None = None, srn: str | None = None, ty: int | None = None) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.hasResource

Check if a resource exists in the database.

Only one of the parameters may be used at a time. The order of precedence is: structured resource name, resource ID, resource type.

Parameters
ri:`str \| None`	A resource ID.
srn:`str \| None`	A structured resource name.
ty:`int \| None`	A resource type.

Returns
`bool`	True if the resource exists, False otherwise.

def insertRequest(self, req: JSON, ts: float) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.insertRequest

Add a request to the requests database.

Parameters
req:`JSON`	The request to store.
ts:`float`	The timestamp of the request.

Returns
`bool`	Boolean value to indicate success or failure.

def insertResource(self, resource: JSON, ri: str): ¶

overrides acme.runtime.DBBinding.DBBinding.insertResource

Insert a resource into the database.

Parameters
resource:`JSON`	The resource to insert.
ri:`str`	The resource ID of the resource.

def prepareStatements(self): ¶

Prepare the PreparedStatements for various SQL operations.

This method is called after the database connection is established and the tables are created. It prepares the SQL statements for the various operations that can be performed on the database. This includes inserting, updating, and deleting resources, identifiers, child resources, and subscriptions.

Note that prepared statements are only usable within the same connection. Therefore, this method should be called after the connection is established.

def purgeDB(self): ¶

overrides acme.runtime.DBBinding.DBBinding.purgeDB

Purge the database. Remove all data

def purgeStatistics(self): ¶

overrides acme.runtime.DBBinding.DBBinding.purgeStatistics

Purge the statistics DB.

def removeActionRepr(self, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.removeActionRepr

Remove an action representation.

Parameters
ri:`str`	The action's resource ID.

Returns
`bool`	True if the action representation was removed, False otherwise.

def removeBatchNotifications(self, ri: str, nu: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.removeBatchNotifications

Remove the batch notifications for a resource and notification URI.

Parameters
ri:`str`	The resource ID of the resource.
nu:`str`	The notification URI.

Returns
`bool`	True if the batch notifications were removed, False otherwise.

def removeChildResource(self, ri: str, pi: str): ¶

overrides acme.runtime.DBBinding.DBBinding.removeChildResource

Remove a child resource from the childResources DB.

Parameters
ri:`str`	The resource ID of the resource.
pi:`str`	The resource ID of the parent resource.

def removeOldRequests(self, maxRequests: int): ¶

overrides acme.runtime.DBBinding.DBBinding.removeOldRequests

Remove old requests from the database.

Parameters
maxRequests:`int`	The maximum number of requests to keep.

def removeOriginator(self, originator: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.removeOriginator

Remove an originator from the database.

Parameters
originator:`str`	The originator to remove.

Returns
`bool`	Boolean value to indicate success or failure.

def removeSchedule(self, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.removeSchedule

Remove a schedule from the database.

Parameters
ri:`str`	The resource ID of the schedule to remove.

Returns
`bool`	True if the schedule was removed, False otherwise.

def removeSubscriptionRepr(self, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.removeSubscriptionRepr

Remove a subscription representation from the database.

Parameters
ri:`str`	The resource ID of the original `SUB` resource.

Returns
`bool`	True if the subscription representation was removed, False otherwise.

def searchActionsReprsForSubject(self, subjectRi: str) -> Sequence[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.searchActionsReprsForSubject

Search for action representations by subject.

Parameters
subjectRi:`str`	The resource ID of the action representation's subject.

Returns
`Sequence[JSON]`	A list of action representations, or an empty list if not found.

def searchByFragment(self, dct: dict) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.searchByFragment

Search and return all resources that match the given dictionary/document.

Parameters
dct:`dict`	The dictionary/document to search for.

Returns
`list[JSON]`	A list of found resources, or an empty list.

def searchChildResourceIDsByParentRIAndType(self, pi: str, ty: ResourceTypes | list[ResourceTypes] | None = None) -> list[str]: ¶

overrides acme.runtime.DBBinding.DBBinding.searchChildResourceIDsByParentRIAndType

Search for child resources by parent resource ID and optional type.

Parameters
pi:`str`	The parent resource ID.
ty:`ResourceTypes \| list[ResourceTypes] \| None`	The resource type of the child resources to search for, or a list of resource types.

Returns
`list[str]`	A list of child resource IDs, or an empty list if not found.

def searchIdentifiers(self, ri: str | None = None, srn: str | None = None) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.searchIdentifiers

Search for an resource ID OR for a structured name in the identifiers DB.

Either ri or srn shall be given. If both are given then srn is taken.

Parameters
ri:`str \| None`	Resource ID to search for.
srn:`str \| None`	Structured path to search for.

Returns
`list[JSON]`	A list of found identifier documents (see `upsertIdentifier`), or an empty list if not found.

overrides acme.runtime.DBBinding.DBBinding.searchResources

Search for resources by structured resource name, resource ID, CSE-ID, parent resource ID, resource type, or application entity ID.

Only one of the parameters may be used at a time. The order of precedence is: structured resource name, resource ID, CSE-ID, structured resource name, parent resource ID, resource type, application entity ID.

Parameters
ri:`str \| None`	A resource ID.
csi:`str \| None`	A CSE ID.
srn:`str \| None`	A structured resource name.
pi:`str \| None`	A parent resource ID.
ty:`int \| None`	A resource type.
aei:`str \| None`	An application entity ID.

Returns
`list[JSON]`	A list of found resource documents, or an empty list.

def searchSchedulesForParent(self, pi: str) -> list[JSON]: ¶

overrides acme.runtime.DBBinding.DBBinding.searchSchedulesForParent

Search for schedules in the database.

Parameters
pi:`str`	The resource ID of the parent resource.

Returns
`list[JSON]`	List of Documents. May be empty.

def searchStatistics(self) -> JSON: ¶

overrides acme.runtime.DBBinding.DBBinding.searchStatistics

Search for statistics.

Returns
`JSON`	The statistics, or None if not found.

def searchSubscriptionReprs(self, ri: str | None = None, pi: str | None = None) -> list[JSON] | None: ¶

overrides acme.runtime.DBBinding.DBBinding.searchSubscriptionReprs

Search for subscription representations by resource ID or parent resource ID.

Only one of the parameters may be used at a time. The order of precedence is: resource ID, parent resource ID.

Parameters
ri:`str \| None`	A resource ID.
pi:`str \| None`	A parent resource ID.

Returns
`list[JSON] \| None`	A list of found subscription representations, or None.

@start

def start(self): ¶

Start the PostgreSQLBinding.

def updateActionRepr(self, actionRepr: JSON) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.updateActionRepr

Update an action representation.

Parameters
actionRepr:`JSON`	The action representation to update.

Returns
`bool`	True if the action representation was updated, False otherwise.

def updateResource(self, resource: JSON, ri: str) -> JSON: ¶

overrides acme.runtime.DBBinding.DBBinding.updateResource

Update a resource in the database. Only the fields that are not None will be updated.

Parameters
resource:`JSON`	The resource to update.
ri:`str`	The resource ID of the resource.

Returns
`JSON`	The updated resource dirctionary.

def upgradeTables(self): ¶

Upgrade the tables if necessary.

def upsertActionRepr(self, actionRepr: JSON, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.upsertActionRepr

Update or insert an action representation.

Parameters
actionRepr:`JSON`	The action representation to update or insert.
ri:`str`	The resource ID of the action representation.

Returns
`bool`	True if the action representation was updated or inserted, False otherwise.

def upsertChildResource(self, childResource: JSON, ri: str): ¶

overrides acme.runtime.DBBinding.DBBinding.upsertChildResource

Add a child resource to the childResources DB.

Parameters
childResource:`JSON`	The resource to add as a child.
ri:`str`	The resource ID of the resource.

def upsertIdentifier(self, identifierMapping: JSON, structuredPathMapping: JSON, ri: str, srn: str): ¶

overrides acme.runtime.DBBinding.DBBinding.upsertIdentifier

Insert or update an identifier into the identifiers DB and a structured resource name into the structuredResourceNames DB.

Parameters
identifierMapping:`JSON`	The identifier mapping to insert.
structuredPathMapping:`JSON`	The structured path mapping to insert.
ri:`str`	The resource ID of the resource.
srn:`str`	The structured resource name of the resource.

def upsertResource(self, resource: JSON, ri: str): ¶

overrides acme.runtime.DBBinding.DBBinding.upsertResource

Update or insert a resource into the database.

Parameters
resource:`JSON`	The resource to upate or insert.
ri:`str`	The resource ID of the resource.

def upsertSchedule(self, schedule: JSON, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.upsertSchedule

Add or update a schedule in the database.

Parameters
schedule:`JSON`	The schedule to store.
ri:`str`	The resource ID of the schedule.

Returns
`bool`	True if the schedule was added or updated, False otherwise.

def upsertStatistics(self, stats: JSON) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.upsertStatistics

Update or insert statistics.

Parameters
stats:`JSON`	The statistics to update or insert.

Returns
`bool`	True if the statistics were updated or inserted, False otherwise.

def upsertSubscriptionRepr(self, subscription: JSON, ri: str) -> bool: ¶

overrides acme.runtime.DBBinding.DBBinding.upsertSubscriptionRepr

Update or insert a subscription representation into the database.

Parameters
subscription:`JSON`	The subscription representation to update or insert.
ri:`str`	The resource ID of the original `SUB` resource.

Returns
`bool`	True if the subscription representation was updated or inserted, False otherwise.

@validate

def validate(self, config: Configuration): ¶

Validate the configuration for the PostgreSQLBinding.

Parameters
config:`Configuration`	The configuration object containing the settings for the PostgreSQLBinding.

Raises
`ConfigurationError`	If the configuration is invalid.

tableActions: str = ¶

The name of the table for actions.

tableBatchNotifications: str = ¶

The name of the table for batch notifications.

tableChildResources: str = ¶

The name of the table for child resource mappings.

tableIdentidiers: str = ¶

The name of the table for identifier mappings.

tableOriginators: str = ¶

The name of the table for originators.

tableRequests: str = ¶

The name of the table to store requests and responses.

tableResources: str = ¶

The name of the table for resources.

tableSchedules: str = ¶

The name of the table for schedules.

tableStatistics: str = ¶

The name of the table for statistic information.

tableSubscriptions: str = ¶

The name of the table for subscription mappings.

dbConnection: PsyConnection | None = ¶

The database connection object.

dbDatabase = ¶

The name of the database to connect to.

dbHost = ¶

The hostname of the database server.

dbPassword = ¶

The password to connect to the database.

dbPort = ¶

The port of the database server.

dbSchema = ¶

The schema to use in the database.

dbUser = ¶

The username to connect to the database.

def _checkOpenConnection(self): ¶

Check if the database connection is open.

Try to reconnect if the connection is closed.

def _executePrepared(self, statement: str, args: tuple, closure: Callable | None = None) -> Any: ¶

Execute a prepared statement.

This is the main method to execute a prepared statement. It will execute the statement with the given arguments and return the result of the closure, if one is provided.

Almost all database operations are done through this method.

Parameters
statement:`str`	The name of the prepared statement to execute and its parameters.
args:`tuple`	The arguments to pass to the prepared statement. This must be a tuple.
closure:`Callable \| None`	An optional closure callback to process the result of the query. This closure will be passed the cursor object and should return the result of the query.

Returns
`Any`	The result of the closure, if one is provided, or True if no closure is provided.

def _fetchAllRows(self, cursor: PsyCursor) -> list[JSON]: ¶

Fetch the first elements from all rows from the database cursor.

Parameters
cursor:`PsyCursor`	The database cursor to fetch the rows from.

Returns
`list[JSON]`	The fetched rows, or an empty list if no rows were fetched.

def _fetchNumber(self, cursor: PsyCursor) -> int: ¶

Fetch one number from the database cursor.

Parameters
cursor:`PsyCursor`	The database cursor to fetch the number from.

Returns
`int`	The fetched number, or None if no number was fetched.

def _fetchSingleRow(self, cursor: PsyCursor, asList: bool = True) -> Any | list[Any]: ¶

Fetch the first element from the first row from the database cursor.

Parameters
cursor:`PsyCursor`	The database cursor to fetch the row from.
asList:`bool`	Whether to return the row as a list or not.

Returns
`Any \| list[Any]`	The fetched row as a single object or in a list, or None or an empty list if no row was fetched.