tutorial_backend_couchdb.py 5.32 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#!/usr/bin/env python3
# This work is licensed under a Creative Commons CCZero 1.0 Universal License.
# See http://creativecommons.org/publicdomain/zero/1.0/ for more information.
"""
Tutorial for storing Asset Administration Shells, Submodels and Assets in a CouchDB database server, using the
CouchDBObjectStore and CouchDB Backend.

This tutorial also shows the usage of the commit()/update() mechanism for synchronizing objects with an external data
source.
"""

from configparser import ConfigParser
from pathlib import Path

import aas.examples.data.example_aas
import aas.backend.couchdb

# To execute this tutorial, you'll need a running CouchDB server, including an empty database and a user account with
# access to that database.
# After installing CouchDB, you can use the CouchDB web interface "Fauxton" (typically at
# http://localhost:5984/_utils/) to create a new database. Optionally, you can create a new user by adding a document
# to the `_users` database with the following contents (notice that the username is required in two positions):
#
#     {"_id": "org.couchdb.user:<your username>",
#      "name": "<your username>",
#      "password": "<your password>",
#      "roles": [],
#      "type": "user"}
#
# Afterwards you can add the new user to the set of "Members" of your new database (via the "Permissions" section in the
# user interface). Alternatively, you can use the admin credentials with PyI40AAS (see below).

# Step by Step Guide:
# step 1: connecting to a CouchDB server
# step 2: storing objects in the CouchDBObjectStore
# step 3: updating objects from the CouchDB and committing changes


##########################################
# Step 1: Connecting to a CouchDB Server #
##########################################

# Well, actually, connections to the CouchDB server are created by the CouchDB backend, as required. However, we need
# to provide the login credentials to the server for this to work.
#
# Here, we take the test configuration to work with PyI40AAS development environments. You should replace these with
# the url of your CouchDB server (typically http://localhost:5984), the name of the empty database, and the name and
# password of a CouchDB user account which is "member" of this database (see above). Alternatively, you can provide
# your CouchDB server's admin credentials.
config = ConfigParser()
51
52
config.read([Path(__file__).parent.parent.parent / 'test' / 'test_config.default.ini',
             Path(__file__).parent.parent.parent / 'test' / 'test_config.ini'])
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

couchdb_url = config['couchdb']['url']
couchdb_database = config['couchdb']['database']
couchdb_user = config['couchdb']['user']
couchdb_password = config['couchdb']['password']


# Provide the login credentials to the CouchDB backend.
# These credetials are used, whenever communication with this CouchDB server is required (either via the
# CouchDBObjectStore or via the update()/commit() backend.
aas.backend.couchdb.register_credentials(couchdb_url, couchdb_user, couchdb_password)

# Now, we create a CouchDBObjectStore as an interface for managing the objects in the CouchDB server.
object_store = aas.backend.couchdb.CouchDBObjectStore(couchdb_url, couchdb_database)


#####################################################
# Step 2: Storing objects in the CouchDBObjectStore #
#####################################################

# Create some example objects
example_submodel1 = aas.examples.data.example_aas.create_example_asset_identification_submodel()
example_submodel2 = aas.examples.data.example_aas.create_example_bill_of_material_submodel()

# The CouchDBObjectStore behaves just like other ObjectStore implementations (see `tutorial_storage.py`). The objects
# are transferred to the CouchDB immediately. Additionally, the `source` attribute is set automatically, so update() and
# commit() will work automatically (see below).
object_store.add(example_submodel1)
object_store.add(example_submodel2)


###################################################################
# Step 3: Updating Objects from the CouchDB and Commiting Changes #
###################################################################

# Since the CouchDBObjectStore has set the `source` attribute of our Submodel objects, we can now use update() and
# commit() to synchronize changes to these objects with the database. The `source` indicates (via its URI scheme) that
# the CouchDB backend is used for the synchronization and references the correct CouchDB server url and database. For
# this to work, we must make sure to `import aas.backend.couchdb` at least once in this Python application, so the
# CouchDB backend is loaded.

# Fetch recent updates from the server
example_submodel1.update()

# Make some changes to a Property within the submodel
prop = example_submodel1.get_referable('ManufacturerName')
assert(isinstance(prop, aas.model.Property))

prop.value = "RWTH Aachen"

# Commit (upload) these changes to the CouchDB server
# We can simply call commit() on the Property object. It will check the `source` attribute of the object itself as well
# as the source attribute of all ancestors in the object hierarchy (including the Submodel) and commit the changes to
# all of these external data sources.
prop.commit()


############
# Clean up #
############

# Let's delete the Submodels from the CouchDB to leave it in a clean state
object_store.discard(example_submodel1)
object_store.discard(example_submodel2)