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 ricxappframe.xapp_frame._BaseXapp(rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False, post_init=None)

This class initializes RMR, starts a thread that checks for incoming messages, provisions an SDL object and optionally creates a config-file watcher. This private base class should not be instantiated by clients directly, but it defines many public methods that may be used by clients.

If environment variable CONFIG_FILE is defined, and that variable contains a path to an existing file, a watcher is defined to monitor modifications (writes) to that file using the Linux kernel’s inotify feature. The watcher must be polled by calling method config_check().

Parameters:

rmr_port: int (optional, default is 4562)

Port on which the RMR library listens for incoming messages.

rmr_wait_for_ready: bool (optional, default is True)

If this is True, then init waits until RMR is ready to send, which includes having a valid routing file. This can be set to False if the client wants to receive only.

use_fake_sdl: bool (optional, default is False)

if this is True, it uses the DBaaS “fake dict backend” instead of Redis or other backends. Set this to True when developing an xapp or during unit testing to eliminate the need for DBaaS.

post_init: function (optional, default is None)

Runs this user-provided function at the end of the init method; its signature should be post_init(self)

get_service(host, service)

To find the url for connecting to the service

Parameters:

host: string

defines the hostname in the url

service: string

defines the servicename in the url

Returns:

string

url for the service

do_post(plt_namespace, url, msg)

registration of the xapp using the url and json msg

Parameters:

plt_namespace: string

platform namespace where the xapp is running

url: string

url for xapp registration

msg: string

json msg containing the xapp details

Returns:

bool

whether or not the xapp is registered

register()

function to registers the xapp

Returns:

bool

whether or not the xapp is registered

registerXapp()

registers the xapp

deregister()

Deregisters the xapp

Returns:

bool

whether or not the xapp is registered

xapp_shutdown()

Deregisters the xapp while shutting down

rmr_get_messages()

Returns a generator iterable over all items in the queue that have not yet been read by the client xapp. Each item is a tuple (S, sbuf) where S is a message summary dict and sbuf is the raw message. The caller MUST call rmr.rmr_free_msg(sbuf) when finished with each sbuf to prevent memory leaks!

rmr_send(payload, mtype, retries=100)

Allocates a buffer, sets payload and mtype, and sends

Parameters:

payload: bytes

payload to set

mtype: int

message type

retries: int (optional)

Number of times to retry at the application level before excepting RMRFailure

Returns:

bool

whether or not the send worked after retries attempts

rmr_rts(sbuf, new_payload=None, new_mtype=None, retries=100)

Allows the xapp to return to sender, possibly adjusting the payload and message type before doing so. This does NOT free the sbuf for the caller as the caller may wish to perform multiple rts per buffer. The client needs to free.

Parameters:

sbuf: ctypes c_void_p

Pointer to an rmr message buffer

new_payload: bytes (optional)

New payload to set

new_mtype: int (optional)

New message type (replaces the received message)

retries: int (optional, default 100)

Number of times to retry at the application level

Returns:

bool

whether or not the send worked after retries attempts

rmr_free(sbuf)

Frees an rmr message buffer after use

Note: this does not need to be a class method, self is not used. However if we break it out as a function we need a home for it.

Parameters:

sbuf: ctypes c_void_p

Pointer to an rmr message buffer

sdl_set(namespace, key, value, usemsgpack=True)

** Deprecate Warning ** ** Will be removed in a future function **

Stores a key-value pair to SDL, optionally serializing the value to bytes using msgpack.

Parameters:

namespace: 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.

sdl_get(namespace, key, usemsgpack=True)

** Deprecate Warning ** ** Will be removed in a future function **

Gets the value for the specified namespace and key from SDL, optionally deserializing stored bytes using msgpack.

Parameters:

namespace: 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.

sdl_find_and_get(namespace, prefix, usemsgpack=True)

** Deprecate Warning ** ** Will be removed in a future function **

Gets all key-value pairs in the specified namespace with keys that start with the specified prefix, optionally deserializing stored bytes using msgpack.

Parameters:

nnamespaces: string

SDL namespace

prefix: string

the key prefix

usemsgpack: boolean (optional, default is True)

If usemsgpack is True, the byte array stored by SDL is deserialized using msgpack to yield the original value that was stored. If usemsgpack is False, the byte array stored by SDL is returned without further processing.

Returns:

Dictionary of key-value pairs

Each key has the specified prefix. The value object (its type) depends on the usemsgpack parameter, but is either a Python object or raw bytes as discussed above. Answers an empty dictionary if no keys matched the prefix.

sdl_delete(namespace, key)

** Deprecate Warning ** ** Will be removed in a future function **

Deletes the key-value pair with the specified key in the specified namespace.

Parameters:

namespace: string

SDL namespace

key: string

SDL key

get_list_gnb_ids()

Retrieves the list of gNodeb identity entities

gNodeb information is stored in SDL by E2Manager. Therefore, gNode information is stored in SDL’s e2Manager namespace as protobuf serialized.

Returns:

List: (NbIdentity)

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

get_list_enb_ids()

Retrieves the list of eNodeb identity entities

eNodeb information is stored in SDL by E2Manager. Therefore, eNode information is stored in SDL’s e2Manager namespace as protobuf serialized.

Returns:

List: (NbIdentity)

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetNodeb(inventoryName)

Returns nodeb info In RNIB SDL key is defined following way: RAN:<inventoryName>

Parameters:

inventoryName: string

Returns:

NodebInfo()

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetNodebByGlobalNbId(nodeType, plmnId, nbId)

Returns nodeb identity based on type, plmn id and node id In RNIB SDL key is defined following way: <nodeType>:<plmnId>:<nbId>

Parameters:

nodeType: string

plmnId: string

nbId: string

Returns:

NbIdentity()

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetCellList(inventoryName)

Returns nodeb served cell list from the saved node data In RNIB SDL key is defined following way: RAN:<inventoryName>

Parameters:

nodeType: string

plmnId: string

nbId: string

Returns:

ServedCellInfo() in case of ENB

ServedNRCell() in case of GNB

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetCellById(cell_type, cell_id)

Returns cell info by cell type and id. In RNIB SDL keys are defined based on the cell type: ENB type CELL:<cell_id> GNB type NRCELL:<cell_id>

Parameters:

cell_type: string

Available cell types - ENB - GNB

Returns:

Cell()

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetListNodebIds()

Returns both enb and gnb NbIdentity list

Returns:

List: (NbIdentity)

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetCell(inventoryName, pci)

Returns cell info using pci In RNIB SDL key is defined following way: PCI:<inventoryName>:<pci hex val>

Parameters:

inventoryName: string

pci: int

Returns:

Cell()

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

GetRanFunctionDefinition(inventoryName, ran_function_oid)

Returns GNB ran function definition list based on the ran_function_oid In RNIB SDL key is defined following way: RAN:<inventoryName>

Parameters:

inventoryName: string

ran_function_oid: int

Returns:

array of ran_function_definition matching to ran_function_oid

Raises:

SdlTypeError: If function’s argument is of an inappropriate type.

NotConnected: If SDL is not connected to the backend data storage.

RejectedByBackend: If backend data storage rejects the request.

BackendError: If the backend data storage fails to process the request.

healthcheck()

this needs to be understood how this is supposed to work

config_check(timeout=0)

Checks the watcher for configuration-file events. The watcher prerequisites and event mask are documented in __init__().

Parameters:

timeout: int (optional)

Number of seconds to wait for a configuration-file event, default 0.

Returns:

List of Events, possibly empty

An event is a tuple with objects wd, mask, cookie and name. For example:

Event(wd=1, mask=1073742080, cookie=0, name='foo')

stop()

cleans up and stops the xapp rmr thread (currently). This is critical for unit testing as pytest will never return if the thread is running.

TODO: can we register a ctrl-c handler so this gets called on ctrl-c? Because currently two ctrl-c are needed to stop.

Class RMRXapp

Application writers should extend this class to implement a reactive Xapp; also see class Xapp.

class ricxappframe.xapp_frame.RMRXapp(default_handler, config_handler=None, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False, post_init=None)

Represents an Xapp that reacts only to RMR messages; i.e., the Xapp only performs an action when a message is received. Clients should invoke the run method, which has a loop that waits for RMR messages and calls the appropriate client-registered consume callback on each.

If environment variable CONFIG_FILE is defined, and that variable contains a path to an existing file, this class polls a watcher defined on that file to detect file-write events, and invokes a configuration-change handler on each event. The handler is also invoked at startup. If no handler function is supplied to the constructor, this class defines a default handler that only logs a message.

Parameters:

default_handler: function

A function with the signature (summary, sbuf) to be called when a message type is received for which no other handler is registered.

default_handler argument summary: dict

The RMR message summary, a dict of key-value pairs

default_handler argument sbuf: ctypes c_void_p

Pointer to an RMR message buffer. The user must call free on this when done.

config_handler: function (optional, default is documented above)

A function with the signature (json) to be called at startup and each time a configuration-file change event is detected. The JSON object is read from the configuration file, if the prerequisites are met.

config_handler argument json: dict

The contents of the configuration file, parsed as JSON.

rmr_port: integer (optional, default is 4562)

Initialize RMR to listen on this port

rmr_wait_for_ready: boolean (optional, default is True)

Wait for RMR to signal ready before starting the dispatch loop

use_fake_sdl: boolean (optional, default is False)

Use an in-memory store instead of the real SDL service

post_init: function (optional, default None)

Run this function after the app initializes and before the dispatch loop starts; its signature should be post_init(self)

register_callback(handler, message_type)

registers this xapp to call handler(summary, buf) when an rmr message is received of type message_type

Parameters:

handler: function

a function with the signature (summary, sbuf) to be called when a message of type message_type is received

summary: dict

the rmr message summary

sbuf: ctypes c_void_p

Pointer to an rmr message buffer. The user must call free on this when done.

message:type: int

the message type to look for

Note if this method is called multiple times for a single message type, the “last one wins”.

run(thread=False, rmr_timeout=5, inotify_timeout=0)

This function should be called when the reactive Xapp is ready to start. After start, the Xapp’s handlers will be called on received messages.

Parameters:

thread: bool (optional, default is False)

If False, execution is not returned and the framework loops forever. If True, a thread is started to run the queue read/dispatch loop and execution is returned to caller; the thread can be stopped by calling the .stop() method.

rmr_timeout: integer (optional, default is 5 seconds)

Length of time to wait for an RMR message to arrive.

inotify_timeout: integer (optional, default is 0 seconds)

Length of time to wait for an inotify event to arrive.

stop()

Sets the flag to end the dispatch loop.

Class Xapp

Application writers should extend this class to implement a general Xapp; also see class RMRXapp.

class ricxappframe.xapp_frame.Xapp(entrypoint, rmr_port=4562, rmr_wait_for_ready=True, use_fake_sdl=False)

Represents a generic Xapp where the client provides a single function for the framework to call at startup time (instead of providing callback functions by message type). The Xapp writer must implement and provide a function with a loop-forever construct similar to the run function in the RMRXapp class. That function should poll to retrieve RMR messages and dispatch them appropriately, poll for configuration changes, etc.

Parameters:

entrypoint: function

This function is called when the Xapp class’s run method is invoked. The function signature must be just function(self)

rmr_port: integer (optional, default is 4562)

Initialize RMR to listen on this port

rmr_wait_for_ready: boolean (optional, default is True)

Wait for RMR to signal ready before starting the dispatch loop

use_fake_sdl: boolean (optional, default is False)

Use an in-memory store instead of the real SDL service

run()

This function should be called when the general Xapp is ready to start.

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