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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

unsubscribe_channel removes subscription from one or several channels.

Parameters:

ns: string

SDL namespace

channel: string

channel to unsubscribe

start_event_listener()

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()

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)

healthcheck()

Checks if the sdl connection is healthy.

Returns:

bool

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)

subscribe(args)

internally used subscription function if the dynamic registration has been set

stop()

stops the dynamic service registration/polling

getFileList(regex, fromtime, totime)

internal use only, get the matching files for collect method

collect(zipfiletmpl, fileregexlist, fromtime, totime)

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

read()

reads the stored symptomdata file content

Returns:

string

zipfile name

integer

data lenght

bytes

bytes of the file data

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)

Subscribe(subs_params=None)

subscription request

Parameters:

subs_params: SubscriptionParams

structured subscription data definition defined in subsclient

Returns

——-

SubscriptionResponse

json string of SubscriptionResponse object

UnSubscribe(subs_id=None)

subscription remove

Parameters:

subs_id: int

subscription id returned in SubscriptionResponse

Returns

——-

response.reason: string

http reason

response.status: int

http status code

QuerySubscriptions()

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)

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)

add_handler(method=None, name=None, uri=None, callback=None)

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