1 # Copyright (c) 2019 AT&T Intellectual Property.
2 # Copyright (c) 2018-2019 Nokia.
4 # Licensed under the Apache License, Version 2.0 (the "License");
5 # you may not use this file except in compliance with the License.
6 # You may obtain a copy of the License at
8 # http://www.apache.org/licenses/LICENSE-2.0
10 # Unless required by applicable law or agreed to in writing, software
11 # distributed under the License is distributed on an "AS IS" BASIS,
12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 # See the License for the specific language governing permissions and
14 # limitations under the License.
17 # This source code is part of the near-RT RIC (RAN Intelligent Controller)
18 # platform project (RICP).
23 Examples how to use synchronous API functions of the Shared Data Layer (SDL).
24 Execution of these examples requires:
25 * Following Redis extension commands have been installed to runtime environment:
33 Redis v4.0 or greater is required. Older versions do not support extension modules.
34 Implementation of above commands is produced by RIC DBaaS:
35 https://gerrit.o-ran-sc.org/r/admin/repos/ric-plt/dbaas
36 In official RIC deployments these commands are installed by `dbaas` service to Redis
38 In development environment you may want install commands manually to pod/container, which is
40 * Following environment variables are needed to set to the pod/container where the application
41 utilizing SDL is going to be run.
42 DBAAS_SERVICE_HOST = [redis server address]
43 DBAAS_SERVICE_PORT= [redis server port]
44 DBAAS_MASTER_NAME = [master Redis sentinel name]. Needed to set only if sentinel is in use.
45 DBAAS_SERVICE_SENTINEL_PORT = [Redis sentinel port number]. Needed to set only if sentinel
48 from ricsdl.syncstorage import SyncStorage
49 from ricsdl.exceptions import RejectedByBackend, NotConnected, BackendError
52 # Constants used in the examples below.
54 MY_GRP_NS = 'my_group_ns'
55 MY_LOCK_NS = 'my_group_ns'
58 def _try_func_return(func):
60 Generic wrapper function to call SDL API function and handle exceptions if they are raised.
64 except RejectedByBackend as exp:
65 print(f'SDL function {func.__name__} failed: {str(exp)}')
66 # Permanent failure, just forward the exception
68 except (NotConnected, BackendError) as exp:
69 print(f'SDL function {func.__name__} failed for a temporal error: {str(exp)}')
70 # Here we could have a retry logic
73 # Creates SDL instance. The call creates connection to the SDL database backend.
74 mysdl = _try_func_return(SyncStorage)
76 # Creates SDL instance what utilizes a fake database backend. Fake database is meant to
77 # be used only at development phase of SDL clients. It does not provide more advanced
79 # mysdl = _try_func_return(lambda: SyncStorage(fake_db_backend='dict'))
82 # Sets a value 'my_value' for a key 'my_key' under given namespace. Note that value
83 # type must be bytes and multiple key values can be set in one set function call.
84 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'my_value'}))
87 # Gets the value of 'my_value' under given namespace.
88 # Note that the type of returned value is bytes.
89 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key', 'someting not existing'}))
90 for key, val in my_ret_dict.items():
91 assert val.decode("utf-8") == u'my_value'
94 # Sets a value 'my_value2' for a key 'my_key' under given namespace only if the old value is
96 # Note that value types must be bytes.
97 was_set = _try_func_return(lambda: mysdl.set_if(MY_NS, 'my_key', b'my_value', b'my_value2'))
98 assert was_set is True
99 # Try again. This time value 'my_value2' won't be set, because the key has already 'my_value2'
101 was_set = _try_func_return(lambda: mysdl.set_if(MY_NS, 'my_key', b'my_value', b'my_value2'))
102 assert was_set is False
105 # Sets a value 'my_value' for a key 'my_key2' under given namespace only if the key doesn't exist.
106 # Note that value types must be bytes.
107 was_set = _try_func_return(lambda: mysdl.set_if_not_exists(MY_NS, 'my_key2', b'my_value'))
108 assert was_set is True
109 # Try again. This time the key 'my_key2' already exists.
110 was_set = _try_func_return(lambda: mysdl.set_if_not_exists(MY_NS, 'my_key2', b'my_value'))
111 assert was_set is False
114 # Removes a key 'my_key' under given namespace.
115 _try_func_return(lambda: mysdl.remove(MY_NS, 'my_key'))
116 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, 'my_key'))
117 assert my_ret_dict == {}
120 # Removes a key 'my_key' under given namespace only if the old value is 'my_value'.
121 was_removed = _try_func_return(lambda: mysdl.remove_if(MY_NS, 'my_key2', b'my_value'))
122 assert was_removed is True
123 # Try again to remove not anymore existing key 'my_key'.
124 was_removed = _try_func_return(lambda: mysdl.remove_if(MY_NS, 'my_key2', b'my_value'))
125 assert was_removed is False
128 # Removes all the keys under given namespace.
129 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'something'}))
130 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key'}))
131 assert my_ret_dict != {}
133 _try_func_return(lambda: mysdl.remove_all(MY_NS))
134 my_ret_dict = _try_func_return(lambda: mysdl.get(MY_NS, {'my_key'}))
135 assert my_ret_dict == {}
138 # Finds keys under given namespace that are matching to given key prefix 'my_k'.
139 _try_func_return(lambda: mysdl.set(MY_NS, {'my_key': b'my_value'}))
140 ret_keys = _try_func_return(lambda: mysdl.find_keys(MY_NS, 'my_k*'))
141 assert ret_keys == ['my_key']
144 # Finds keys and their values under given namespace that are matching to given key search
146 # Note that the type of returned value is bytes.
147 ret_key_values = _try_func_return(lambda: mysdl.find_and_get(MY_NS, 'my_k*'))
148 assert ret_key_values == {'my_key': b'my_value'}
150 _try_func_return(lambda: mysdl.remove_all(MY_NS))
153 # Adds a member 'a' to a group 'my_group' under given namespace. A group is a unique collection of
155 # Note that member type must be bytes and multiple members can be set in one set function call.
156 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a'}))
157 # Try again to add a member 'a'. This time 'a' won't be added, because 'a' belongs already to
159 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a'}))
162 # Gets group 'my_group' members under given namespace.
163 # Note that the type of returned member is bytes.
164 ret_members = _try_func_return(lambda: mysdl.get_members(MY_GRP_NS, 'my_group'))
165 assert ret_members == {b'a'}
168 # Checks if 'a' is a member of the group 'my_group' under given namespace.
169 was_member = _try_func_return(lambda: mysdl.is_member(MY_GRP_NS, 'my_group', b'a'))
170 assert was_member is True
171 was_member = _try_func_return(lambda: mysdl.is_member(MY_GRP_NS, 'my_group', b'not a member'))
172 assert was_member is False
175 # Returns the count of members of a group 'my_group' under given namespace.
176 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
177 assert ret_count == 1
180 # Removes the member 'a' of the group 'my_group' under given namespace.
181 _try_func_return(lambda: mysdl.remove_member(MY_GRP_NS, 'my_group', {b'a', b'not exists'}))
182 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
183 assert ret_count == 0
186 # Removes the group 'my_group' under given namespace.
187 _try_func_return(lambda: mysdl.add_member(MY_GRP_NS, 'my_group', {b'a', b'b', b'c'}))
188 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
189 assert ret_count == 3
191 _try_func_return(lambda: mysdl.remove_group(MY_GRP_NS, 'my_group'))
192 ret_count = _try_func_return(lambda: mysdl.group_size(MY_GRP_NS, 'my_group'))
193 ret_members = _try_func_return(lambda: mysdl.get_members(MY_GRP_NS, 'my_group'))
194 assert ret_count == 0
195 assert ret_members == set()
198 # Gets a lock 'my_lock' resource under given namespace.
199 # Note that this function does not take a lock, you need to call 'acquire' function to take
200 # the lock to yourself.
201 my_lock = _try_func_return(lambda: mysdl.get_lock_resource(MY_LOCK_NS, "my_lock", expiration=5.5))
202 assert my_lock is not None
205 # Acquires a lock from the lock resource. Return True if lock was taken within given retry limits.
206 was_acquired = _try_func_return(lambda: my_lock.acquire(retry_interval=0.5, retry_timeout=2))
207 assert was_acquired is True
208 # Try again. This time a lock won't be acquired successfully, because we have a lock already.
209 was_acquired = _try_func_return(lambda: my_lock.acquire(retry_interval=0.1, retry_timeout=0.2))
210 assert was_acquired is False
213 # Refreshs the remaining validity time of the existing lock back to the initial value.
214 _try_func_return(my_lock.refresh)
217 # Gets the remaining validity time of the lock.
218 ret_time = _try_func_return(my_lock.get_validity_time)
223 _try_func_return(my_lock.release)
226 # Locking example what utilizes python 'with' statement with SDL lock.
227 # The lock is released automatically when we are out of the scope of
228 # 'the with my_lock' statement.
229 my_lock = _try_func_return(lambda: mysdl.get_lock_resource(MY_LOCK_NS, "my_lock", 2.5))
231 # Just an example how to use lock API
232 time_left = _try_func_return(my_lock.get_validity_time)
234 # Add here operations what needs to be done under a lock, for example some
235 # operations with a shared resources what needs to be done in a mutually
238 # Lock is not anymore hold here
241 # Closes the SDL connection.