4.2. couchdb - Store and Retrieve AAS-objects in a CouchDB

This module adds the functionality of storing and retrieving Identifiable objects in a CouchDB.

The CouchDBBackend takes care of updating and committing objects from and to the CouchDB, while the CouchDBObjectStore handles adding, deleting and otherwise managing the AAS objects in a specific CouchDB.

class CouchDBBackend

This Backend stores each Identifiable object as a single JSON document in the configured CouchDB database. Each document’s id is build from the object’s identifier. The document’s contents comprise a single property data, containing the JSON serialization of the BaSyx Python SDK object. The adapter.json package is used for serialization and deserialization of objects.

classmethod commit_object(committed_object: Referable, store_object: Referable, relative_path: List[str]) → None

Function (class method) to be called when an object shall be committed (local changes pushed to the external data source) via this backend implementation.

It is automatically called by the commit() implementation, when the source URI of the object or the source URI one of its ancestors in the AAS object containment hierarchy include an URI schema for which this backend has been registered. Both of the objects are passed to this function: the one which shall be committed (committed_object) and its ancestor with the relevant source URI (store_object). They may be the same, the committed object has a source with the relevant schema itself. Additionally, the relative_path from the store_object down to the committed_object is provided.

The backend MUST ensure to commit all local changes of at least the committed_object and all objects contained within it (if any) to the data source. It MAY additionally commit changes to other objects (i.e. the store_object and any additional contained object).

For this purpose a concrete implementation of this method would typically use the source attribute of the store_object to identify the data source. If the data source supports fine-grained access to contained objects, the relative_path may become handy to compose the committed object’s address within the data source’s interface.

Parameters:

  • committed_object – The object which shall be synced to the external data source

  • store_object – The object which originates from the relevant data source (i.e. has the relevant source attribute). It may be the committed_object or one of its ancestors in the AAS object hierarchy.

  • relative_path – List of idShort strings to resolve the committed_object starting at the store_object, such that obj = store_object; for i in relative_path: obj = obj.get_referable(i) resolves to the committed_object. In case that store_object is committed_object, it is an empty list.

Raises:

BackendNotAvailableException – when the external data source cannot be reached

classmethod do_request(url: str, method: str = 'GET', additional_headers: Dict[str, str] = {}, body: bytes | None = None) → MutableMapping[str, Any]

Perform an HTTP(S) request to the CouchDBServer, parse the result and handle errors

Parameters:

  • url – The HTTP or HTTPS URL to request

  • method – The HTTP method for the request

  • additional_headers – Additional headers to insert into the request. The default headers include ‘connection: keep-alive’, ‘accept-encoding: …’, ‘authorization: basic …’, ‘Accept: …’.

  • body – Request body for POST, PUT, and PATCH requests

Returns:

The parsed JSON data if the request method is other than ‘HEAD’ or the response headers for ‘HEAD’ requests

classmethod update_object(updated_object: Referable, store_object: Referable, relative_path: List[str]) → None

Function (class method) to be called when an object shall be updated (local object updated with changes from the external data source) via this backend implementation.

It is automatically called by the update() implementation, when the source URI of the object or the source URI one of its ancestors in the AAS object containment hierarchy include an URI schema for which this backend has been registered. Both of the objects are passed to this function: the one which shall be update (updated_object) and its ancestor with the relevant source URI (store_object). They may be the same, the updated object has a source with the relevant schema itself. Additionally, the relative_path from the store_object down to the updated_object is provided.

The backend MUST ensure to update at least the updated_object and all objects contained within it (if any) with any changes from the data source. It MAY additionally update other objects (i.e. the store_object and any additional contained object).

For this purpose a concrete implementation of this method would typically use the source attribute of the store_object to identify the data source. If the data source supports fine-grained access to contained objects, the relative_path may become handy to compose the updated object’s address within the data source’s interface.

Parameters:

  • updated_object – The object which shall be synced from the external data source

  • store_object – The object which originates from the relevant data source (i.e. has the relevant source attribute). It may be the committed_object or one of its ancestors in the AAS object hierarchy.

  • relative_path – List of idShort strings to resolve the updated_object starting at the store_object, such that obj = store_object; for i in relative_path: obj = obj.get_referable(i) resolves to the updated_object. In case that store_object is updated_object, it is an empty list.

Raises:

BackendNotAvailableException – when the external data source cannot be reached

exception CouchDBConflictError

Exception raised when an object could not be committed due to an concurrent modification in the database

exception CouchDBConnectionError

Exception raised when the CouchDB server could not be reached

exception CouchDBError
class CouchDBObjectStore(url: str, database: str)

An ObjectStore implementation for Identifiable BaSyx Python SDK objects backed by a CouchDB database server.

All methods of the CouchDBObjectStore are blocking, i.e. they stop the current thread’s execution until they receive a response from the CouchDB server (or encounter a timeout). However, the CouchDBObjectStore objects are thread-safe, as long as no CouchDB credentials are added (via register_credentials()) during transactions.

add(x: Identifiable) → None

Add an object to the store

Raises:

  • KeyError – If an object with the same id exists already in the database

  • CouchDBError – If error occur during the request to the CouchDB server (see _do_request() for details)

check_database(create=False)

Check if the database exists and created it if not (and requested to do so)

Parameters:

create – If True and the database does not exist, try to create it

Raises:

CouchDBError – If error occur during the request to the CouchDB server (see _do_request() for details)

discard(x: Identifiable, safe_delete=False) → None

Delete an Identifiable AAS object from the CouchDB database

Parameters:

  • x – The object to be deleted

  • safe_delete – If True, only delete the object if it has not been modified in the database in comparison to the provided revision. This uses the CouchDB revision token and thus only works with CouchDBIdentifiable objects retrieved from this database.

Raises:

  • KeyError – If the object does not exist in the database

  • CouchDBConflictError – If safe_delete is True and the object has been modified or deleted in the database

  • CouchDBError – If error occur during the request to the CouchDB server (see _do_request() for details)

generate_source(identifiable: Identifiable)

Generates the source string for an Identifiable object that is backed by the Couchdb

Parameters:

identifiable – Identifiable object

get_identifiable(identifier: str) → Identifiable

Retrieve an AAS object from the CouchDB by its Identifier

Raises:

  • KeyError – If no such object is stored in the database

  • CouchDBError – If error occur during the request to the CouchDB server (see _do_request() for details)

get_identifiable_by_couchdb_id(couchdb_id: str) → Identifiable

Retrieve an AAS object from the CouchDB by its couchdb-ID-string

Raises:

  • KeyError – If no such object is stored in the database

  • CouchDBError – If error occur during the request to the CouchDB server (see _do_request() for details)

exception CouchDBResponseError

Exception raised by when an HTTP of the CouchDB server could not be handled (e.g. no JSON body)

exception CouchDBServerError(code: int, error: str, reason: str, *args)

Exception raised when the CouchDB server returns an unexpected error code

exception CouchDBSourceError

Exception raised when the source has the wrong format

delete_couchdb_revision(url: str)

Delete the CouchDB revision from the revision store for the given URL to a CouchDB Document

Parameters:

url – URL to the CouchDB document

get_couchdb_revision(url: str) → str | None

Get the CouchDB revision from the revision store for the given URL to a CouchDB Document

Parameters:

url – URL to the CouchDB document

Returns:

CouchDB-revision, if there is one, otherwise returns None

register_credentials(url: str, username: str, password: str)

Register the credentials of a CouchDB server to the global credentials store

Warning

Do not use this function, while other threads may be accessing the credentials via the CouchDBObjectStore or update or commit functions of Referable objects!

Parameters:

  • url – Toplevel URL

  • username – Username to that CouchDB instance

  • password – Password to the Username

set_couchdb_revision(url: str, revision: str)

Set the CouchDB revision of the given document in the revision store

Parameters:

  • url – URL to the CouchDB document

  • revision – CouchDB revision