acme.runtime.DBBinding.DBBinding

class documentation

class DBBinding(ABC):

Known subclasses: acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

View In Hierarchy

This abstract class defines the interface for database bindings.

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	`countBatchNotifications`	Return the number of batch notifications for a resource and notification URI.
Method	`countResources`	Return the number of resources in the database.
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	`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	`updateActionRepr`	Update an action representation.
Method	`updateResource`	Update a resource in the database. Only the fields that are not None will be updated.
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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Backup the database to a directory.

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

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

@abstractmethod

def closeDB(self): ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Close the database.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

def countResources(self) -> int: ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Return the number of resources in the database.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Remnove all stored requests from the database.

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

@abstractmethod

def deleteResource(self, ri: str): ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Delete a resource from the database.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Return all action representations.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Get all schedules from the database.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Insert a resource into the database.

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

@abstractmethod

def purgeDB(self): ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Purge the database. Remove all data

@abstractmethod

def purgeStatistics(self): ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Purge the statistics DB.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Remove an action representation.

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

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

def removeOldRequests(self, maxRequests: int): ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Remove old requests from the database.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Remove an originator from the database.

Parameters
originator:`str`	The originator to remove.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

def searchStatistics(self) -> JSON: ¶

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Search for statistics.

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

Update an action representation.

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

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

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.

@abstractmethod

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

overridden in acme.plugins.database.PostgreSQLBinding.PostgreSQLBinding, acme.plugins.database.TinyDBBinding.TinyDBBinding

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.