User Guide — xapp-frame-py master documentation

# 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