User Guide¶
This document explains how to develop an Xapp using the RIC Xapp framework. Information for maintainers of this framework is in the Developer Guide.
Xapp writers should use the public classes and methods from the Xapp Python framework package as documented below.
Class _BaseXapp¶
Although this base class should not be used directly, it is inherited by the public classes shown below and all of this class’s public methods are available for use by application writers.
Class RMRXapp¶
Application writers should extend this class to implement a reactive Xapp; also see class Xapp.
Class Xapp¶
Application writers should extend this class to implement a general Xapp; also see class RMRXapp.
Class SDLWrapper¶
Application writers may instantiate this class directly to communicate with the SDL service.
- class ricxappframe.xapp_sdl.SDLWrapper(use_fake_sdl=False)[source]¶
Provides convenient wrapper methods for using the SDL Python interface. Optionally uses msgpack for binary (de)serialization: see https://msgpack.org/index.html
Published as a standalone module (and kept separate from the Xapp framework classes) so these features can be used outside Xapps.
- set(ns, key, value, usemsgpack=True)[source]¶
Stores a key-value pair, optionally serializing the value to bytes using msgpack.
TODO: discuss whether usemsgpack should default to True or False here. This seems like a usage statistic question (that we don’t have enough data for yet). Are more uses for an xapp to write/read their own data, or will more xapps end up reading data written by some other thing? I think it’s too early to know.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- set_if(ns, key, old_value, new_value, usemsgpack=True)[source]¶
Conditionally modify the value of a key if the current value in data storage matches the user’s last known value.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- old_value:
Lask known object or byte array. See the usemsgpack parameter.
- new_value:
Object or byte array to be written. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- Returns:
- bool
True for successful modification, false if the user’s last known data did not match the current value in data storage.
- set_if_not_exists(ns, key, value, usemsgpack=True)[source]¶
Write data to SDL storage if key does not exist.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- Returns:
- bool
True for successful modification, false if the user’s last known data did not match the current value in data storage.
- get(ns, key, usemsgpack=True)[source]¶
Gets the value for the specified namespace and key, optionally deserializing stored bytes using msgpack.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- usemsgpack: boolean (optional, default is True)
If usemsgpack is True, the byte array stored by SDL is deserialized using msgpack to yield the original object that was stored. If usemsgpack is False, the byte array stored by SDL is returned without further processing.
- Returns:
- Value
See the usemsgpack parameter for an explanation of the returned value type. Answers None if the key is not found.
- find_keys(ns, prefix)[source]¶
Find all keys matching search pattern under the namespace.
- Parameters:
- ns: string
SDL namespace
- prefix: string
Key search pattern
- Returns:
- keys: list
A list of found keys.
- find_and_get(ns, prefix, usemsgpack=True)[source]¶
Gets all key-value pairs in the specified namespace with keys that start with the specified prefix, optionally deserializing stored bytes using msgpack.
- Parameters:
- ns: string
SDL namespace
- prefix: string
the key prefix
- usemsgpack: boolean (optional, default is True)
If usemsgpack is True, every byte array stored by SDL is deserialized using msgpack to yield the original value that was stored. If usemsgpack is False, every byte array stored by SDL is returned without further processing.
- Returns:
- Dictionary of key-value pairs
Each key has the specified prefix. See the usemsgpack parameter for an explanation of the returned value types. Answers an empty dictionary if no keys matched the prefix.
- delete(ns, key)[source]¶
Deletes the key-value pair with the specified key in the specified namespace.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- delete_if(ns, key, value, usemsgpack=True)[source]¶
Conditionally remove data from SDL storage if the current data value matches the user’s last known value.
- Parameters:
- ns: string
SDL namespace
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- Returns:
- bool
True if successful removal, false if the user’s last known data did not match the current value in data storage.
- add_member(ns, group, member, usemsgpack=True)[source]¶
Add new members to a SDL group under the namespace.
- Parameters:
- ns: string
SDL namespace
- group: string
group name
- member:
member to be added
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- remove_member(ns, group, member, usemsgpack=True)[source]¶
Remove members from a SDL group.
- Parameters:
- ns: string
SDL namespace
- group: string
group name
- member:
member to be removed
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- remove_group(ns, group)[source]¶
Remove a SDL group along with its members.
- Parameters:
- ns: string
SDL namespace
- group: string
group name to remove
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- get_members(ns, group, usemsgpack=True)[source]¶
Get all the members of a SDL group.
- Parameters:
- ns: string
SDL namespace
- group: string
group name to retrive
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- Returns:
- Set[str] or Set[bytes]
A set of the members of the group.
- None
- is_member(ns, group, member, usemsgpack=True)[source]¶
Validate if a given member is in the SDL group.
- Parameters:
- ns: string
SDL namespace
- group: string
group name
- member:
member to validate
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- Returns:
- bool
True if member was in the group, false otherwise.
- group_size(ns, group)[source]¶
Return the number of members in a group. If the group does not exist, value 0 is returned.
- Parameters:
- ns: string
SDL namespace
- group: string
group name to retrive size
- usemsgpack: boolean (optional, default is True)
Determines whether the member is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the member to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the member can be anything that is serializable by msgpack. If usemsgpack is False, the member must be bytes.
- Returns:
- int
Number of members in a group.
- set_and_publish(ns, channel, event, key, value, usemsgpack=True)[source]¶
Publish event to channel after writing data.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- set_if_and_publish(ns, channel, event, key, old_value, new_value, usemsgpack=True)[source]¶
Publish event to channel after conditionally modifying the value of a key if the current value in data storage matches the user’s last known value.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- key: string
SDL key
- old_value:
Lask known object or byte array. See the usemsgpack parameter.
- new_value:
Object or byte array to be written. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the old_value & new_value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the old_value & new_value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the old_value & new_value can be anything that is serializable by msgpack. If usemsgpack is False, the old_value & new_value must be bytes.
- Returns:
- bool
True for successful modification, false if the user’s last known data did not match the current value in data storage.
- set_if_not_exists_and_publish(ns, channel, event, key, value, usemsgpack=True)[source]¶
Publish event to channel after writing data to SDL storage if key does not exist.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- Returns:
- bool
True if key didn’t exist yet and set operation was executed, false if key already existed and thus its value was left untouched.
- remove_and_publish(ns, channel, event, key)[source]¶
Publish event to channel after removing data.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- key: string
SDL key
- remove_if_and_publish(ns, channel, event, key, value, usemsgpack=True)[source]¶
Publish event to channel after removing key and its data from database if the current data value is expected one.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- key: string
SDL key
- value:
Object or byte array to store. See the usemsgpack parameter.
- usemsgpack: boolean (optional, default is True)
Determines whether the value is serialized using msgpack before storing. If usemsgpack is True, the msgpack function packb is invoked on the value to yield a byte array that is then sent to SDL. Stated differently, if usemsgpack is True, the value can be anything that is serializable by msgpack. If usemsgpack is False, the value must be bytes.
- Returns:
- bool
True if successful removal, false if the user’s last known data did not match the current value in data storage.
- remove_all_and_publish(ns, channel, event)[source]¶
Publish event to channel after removing all keys under the namespace.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to publish event
- event: string
published message
- subscribe_channel(ns, cb, channel)[source]¶
Subscribes the client to the specified channels.
- Parameters:
- ns: string
SDL namespace
- cb:
A function that is called when an event on channel is received.
- channel: string
channel to subscribe
- unsubscribe_channel(ns, channel)[source]¶
unsubscribe_channel removes subscription from one or several channels.
- Parameters:
- ns: string
SDL namespace
- channel: string
channel to unsubscribe
- start_event_listener()[source]¶
start_event_listener creates an event loop in a separate thread for handling events from subscriptions. The registered callback function will be called when an event is received.
- handle_events()[source]¶
handle_events is a non-blocking function that returns a tuple containing channel name and a list of message(s) received from an event. The registered callback function will still be called when an event is received.
This function is called if SDL user decides to handle notifications in its own event loop. Calling this function after start_event_listener raises an exception. If there are no notifications, these returns None.
- Returns:
- Tuple:
(channel: str, message: list of str)
Class Symptomdata¶
Application writers may instantiate this class directly to communicate with the symptomdata service.
- class ricxappframe.xapp_symptomdata.Symptomdata(service='', servicehost='', path='/tmp/', lwsduri=None, timeout=30)[source]¶
- subscribe(args)[source]¶
internally used subscription function if the dynamic registration has been set
- getFileList(regex, fromtime, totime)[source]¶
internal use only, get the matching files for collect method
- collect(zipfiletmpl, fileregexlist, fromtime, totime)[source]¶
- collects the symptomdata based on the file regular expression match and stored the symptomdata. Optionaly
caller can use fromtime and totime to choose only files matching the access time
- Parameters:
- zipfiletmpl: string
template for zip file name using the strftime format - ex:
"symptomdata"+'-%Y-%m-%d-%H-%M-%S.zip'
- fileregexlist: string array
array for file matching - ex:
('examples/*.csv',)
- fromtime: integer
time value seconds
- totime: integer
time value seconds
- Returns
- ——-
- string
zipfile name
Class NewSubscriber¶
Application writers may instantiate this class directly to communicate REST based subscriptions.
- class ricxappframe.xapp_subscribe.NewSubscriber(uri, timeout=None, local_address='0.0.0.0', local_port=8088, rmr_port=4061)[source]¶
- Subscribe(subs_params=None)[source]¶
subscription request
- Parameters:
- subs_params: SubscriptionParams
structured subscription data definition defined in subsclient
- Returns
- ——-
- SubscriptionResponse
json string of SubscriptionResponse object
- UnSubscribe(subs_id=None)[source]¶
subscription remove
- Parameters:
- subs_id: int
subscription id returned in SubscriptionResponse
- Returns
- ——-
- response.reason: string
http reason
- response.status: int
http status code
- QuerySubscriptions()[source]¶
Query all subscriptions
- Returns:
- response.data: json string
SubscriptionList
- response.reason: string
http reason
- response.status: int
http status code
- ResponseHandler(responseCB=None, server=None)[source]¶
Starts the response handler and set the callback
- Parameters:
- responseCB
Set the callback handler, if not set the the default self._responsePostHandler is used
- server: xapp_rest.ThreadedHTTPServer
if set then the existing xapp_rest.ThreadedHTTPServer handler is used, otherwise a new will be created
- Returns:
- status: boolean
True = success, False = failed
Class RestHandler¶
Application writers may instantiate this class directly to have the xapp REST server service.
- class ricxappframe.xapp_rest.RestHandler(request, client_address, server)[source]¶
- add_handler(method=None, name=None, uri=None, callback=None)[source]¶
Adds the function handler for given uri. The function callback is matched in first matching uri. So prepare your handlers setup in such a way that those won’t override each other. For example you can setup usual xapp handler in this list:
server = ricrest.ThreadedHTTPServer(address, port) server.handler.add_handler(self.server.handler, “GET”, “config”, “/ric/v1/config”, self.configGetHandler) server.handler.add_handler(self.server.handler, “GET”, “healthAlive”, “/ric/v1/health/alive”, self.healthyGetAliveHandler) server.handler.add_handler(self.server.handler, “GET”, “healthReady”, “/ric/v1/health/ready”, self.healthyGetReadyHandler) server.handler.add_handler(self.server.handler, “GET”, “symptomdata”, “/ric/v1/symptomdata”, self.symptomdataGetHandler)
- Parameters:
- method string
http method GET, POST, DELETE
- name string
unique name - used for map name
- uri string
http uri part which triggers the callback function
- cb function
function to be used for http method processing