07-flexcontainer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img style=\"float: right; padding: 10px;\" width=\"200\" src=\"images/logo-onem2m-the-iot-standard.jpg\">\n",
    "\n",
    "# oneM2M - flexContainers and Specializations\n",
    "\n",
    "This notebook demonstrates how to work with &lt;flexContainer> Resources and how to make use of pre-defined and more standardized data structures.\n",
    "\n",
    "&lt;flexContainer> resources cannot directly be instantiated. Instead, they can be seen as a base for  specialized resource definitions with a given structure and semantics.  \n",
    "oneM2M defines in its technical specification *TS-0023* a number of those &lt;flexContainer> specialisations for various application domains. \n",
    "\n",
    "In this notebook we use the &lt;flexContainer> specialization *[colour]*, which consists of three RGB data points, ie. *red*, *green*, and *blue*.\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 400px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "In oneM2M the normal resource types are written as &lt;resourceType>. Specializations, ie. resource types that inherit from a &lt;flexContainer>, are written as <i>[specializationType]</i>.</div>\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "- Create a &lt;flexContainer> [colour] specialization resource \n",
    "- Update a [colour] resource\n",
    "- Retrieve a &lt;flexContainer> resource\n",
    "- Enable &lt;flexContainerInstance> resource\n",
    "- Retrieve &lt;flexContainerInstance> resources\n",
    "\n",
    "## Intitialization\n",
    "The section does import necessary modules and configurations, and prepares the CSE for this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%run src/init.py flexcontainer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Create a &lt;flexContainer> [colour] Resource\n",
    "\n",
    "<img align=\"right\" src=\"images/07/create_flexContainer.png\">\n",
    "\n",
    "\n",
    "This request will create a &lt;flexContainer> resource that follows oneM2M's [cod:colour] specialization.  \n",
    "One advantage of a &lt;flexContainer> over a normal &lt;container> resource is that it contains all data points of a data structure in one place, ie. all data points can be updated at once.\n",
    "\n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 400px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "One important thing to notice that is also different from other requests is that the name of the resource, [cod:color], is the domain's name space and the name of specialization type, not the resource type.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "CREATE (                                           # CREATE request\n",
    "    \n",
    "    # Create the [cod:colour] resource under the Notebook AE\n",
    "    to                      = cseBaseName + '/Notebook-AE',  \n",
    "    \n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',           # Set the originator\n",
    "    requestIdentifier       = '123',               # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                 # Release version indicator\n",
    "    resourceType            = Type.FlexContainer,  # Type of the resource: FlexContainer\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'cod:colour' : {\n",
    "                'resourceName': 'Colour',\n",
    "                'containerDefinition': 'org.onem2m.common.moduleclass.colour',\n",
    "                'red': 0,\n",
    "                'green': 255,\n",
    "                'blue': 0\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "### Requests & Response Attributes\n",
    "\n",
    "The request and response introduce new attributes:\n",
    "\n",
    "| Attribute                 | Short Name | Description                                                                                                                                     |\n",
    "|:--------------------------|:-----------|:------------------------------------------------------------------------------------------------------------------------------------------------|\n",
    "| containerDefinition | cnd | The <i>containerDefinition</i> attribute contains the type of the specialization. |\n",
    "| red | red | A data point of the [cod:colour] specialization that represents the \"red\" colour channel. |\n",
    "| green | green | A data point of the [cod:colour] specialization that represents the \"green\" colour channel. |\n",
    "| blue | blue | A data point of the [cod:colour] specialization that represents the \"blue\" colour channel. |\n",
    "\n",
    "\n",
    "\n",
    "<a id=\"update_colour\"></a>\n",
    "<img align=\"right\" src=\"images/07/update_flexContainer.png\">\n",
    "## Update the [cod:colour] Resource\n",
    "\n",
    "A &lt;flexContainer> specialization can be updated as any other resource. This means that it is possible to update all or only individual data points of a data structure.  \n",
    "In the following request we only update the RGB *red* data point.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "UPDATE (                                            # UPDATE request\n",
    "\n",
    "    # Target the [cod:colour] resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Colour',  \n",
    "\n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'cod:colour': {\n",
    "                'red': 255                          # Assign a new value to the 'red' data point\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"right\" src=\"images/07/retrieve_flexContainer.png\">\n",
    "\n",
    "## Retrieve the [colour]  Resource\n",
    "This request retrieves the full &lt;flexContainer> resource. This request is not different from working with other resource types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RETRIEVE (                                          # RETRIEVE request\n",
    "\n",
    "    # Retrieve the [cod:colour] resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Colour', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img align=\"right\" src=\"images/07/update_flexContainer_2.png\">\n",
    "\n",
    "## Enable &lt;flexContainerInstance> Resources \n",
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 400px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    " Since oneM2M Release 4 it is possible to configure a &lt;flexContainer> to save and store previous versions of itself in &lt;flexContainerInstances>. This functionality is similar to what we already know from &lt;container> and &lt;contentInstance> resources, but only for the state of a &lt;flexContainer>, ie. the custom attributes and <i>labels</i>.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "\n",
    "The following UPDATE requests enables this features by setting the *maxNrOfInstances* attribute to a value. This instructs the CSE to store a couple of old versions of the &lt;flexContainer> resource's data points."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "UPDATE (                                            # UPDATE request\n",
    "\n",
    "    # Target the [cod:colour] resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Colour',  \n",
    "\n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',            # Set the originator\n",
    "    requestIdentifier       = '123',                # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                  # Release version indicator\n",
    "    \n",
    "    # Request Body\n",
    "    primitiveContent = \n",
    "        {\n",
    "            'cod:colour': {\n",
    "                'maxNrOfInstances'  : 10                         # Set the maxNrOfInstances and enable <flexContainerInstances>\n",
    "            }\n",
    "        }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 400px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "When &lt;flexContainerInstance> resources are enabled for &lt;flexContainer>, the CSE automatically saves the current states and any future change to the &lt;flexContainer> resource in a new &lt;flexContainerInstance> resource. It also adds the virtual resources <i>latest</i> and <i>oldest</i> that have the same functionality as for &lt;container> resources.\n",
    "  \n",
    "Similar to &lt;contentInstance> resources, &lt;flexContainerInstance> resources are managed by their parent resource. They can be retrieved and deleted, but not created by a request or updated.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "We can create more &lt;flexContainerInstances> by more [sending UPDATE requests](#update_colour) to the original [cod:colour] resource.\n",
    "\n",
    "<img align=\"right\" src=\"images/07/retrieve_oldest.png\">\n",
    "\n",
    "## Retrieve the oldest &lt;flexContainerInstance> Resource\n",
    "\n",
    "Retrieval of &lt;flexContainerInstance> resources is similar to the retrieval of &lt;contentInstance> resources under a &lt;container>. The virtual resources &lt;latest> and &lt;oldest> provide access to the newest and oldest available &lt;flexContainerInstance> resources."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "RETRIEVE (                                                 # RETRIEVE request\n",
    "\n",
    "    # Retrieve the [cod:colour] resource\n",
    "    to                      = cseBaseName + '/Notebook-AE/Colour/ol', \n",
    "\n",
    "    # Request Parameters\n",
    "    originator              = 'Cmyself',                   # Set the originator\n",
    "    requestIdentifier       = '123',                       # Unique request identifier\n",
    "    releaseVersionIndicator = '3',                         # Release version indicator\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<p>\n",
    "<div style=\"background-color:transparent;border:2px #b42025 solid;padding: 10px;width: calc(100% - 400px);border-radius:10px;\">\n",
    "    <div style=\"color:#b42025;\"><b><i class=\"fa fa-info-circle\" aria-hidden=\"true\"></i>&nbsp; oneM2M</b></div>\n",
    "    <div style=\"color:#545054;\">\n",
    "The &lt;flexContainerInstance> resources are automatically numbered by using the current value of the <i>stateTag</i> attribute. Since this attribute might change independently the numbering of the &lt;flexContainerInstance> resources is not necessarily continuous.\n",
    "<br>\n",
    "<br>    \n",
    "Note, that the structure name of the &lt;flexContainer> and &lt;flexContainerInstance> are both [cod:colour]. The only way to distinguish them is the <i>resourceType</i> attribute, which is \"28\" or \"58\", respectively.\n",
    "    </div>\n",
    "</div>\n",
    "</p>\n",
    "\n",
    "&nbsp;"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}