Overview

Current DAC design assumes that AWC will behave as a proxy to LISA API and will be it's only consumer. Main reason for such decision was dictated by requirement of tracking and controlling LISA usage to prevent situation when application is currently started and external client (eg. DAC Manager) would call LISA's uninstall API. This would cause undefined behaviour, due to removal of application during active state. Covering LISA's API by AWC would prevent such situation by blocking uninstall request on AWC level.

Above approach unfortunately has cons:

Violates SRP, AWC should be only responsible for controlling application window(size, position) and state (start, stop).
It creates strong dependency between AWC and LISA.
Code bloat by providing unnecessary proxy layer.
LISA by design cannot be used standalone, and some external application manger needs to protect access to LISA to prevent above situation.

This design resolve this issue by extending LISA API with locking mechanism, decoupling it from AWC and expose LISA API to external clients.

Design

LISA API should be extended with three additional methods: lock, unlock, getLockInfo. Those methods are used by entity which manages application state (AWC) to block any operations (uninstall) on application during it's active state (started, suspended). Lock is performed with id, version of the application, lock owner and lock reason, we are only blocking specific version of application.

After sending asynchronous request (uninstall) to LISA, requesting client (eg. DAC Manager), if application is currently used (active - locked by AWC), will receive error result with information about lock reason(eg. ERROR_APP_ACTIVE). Additional API method getLockInfo will allow to check who is the lock owner.

If application is not currently in locked state (is in stopped state) asynchronous operation can be performed.

From other end if AWC will receive Start (or initiate itself) request from MainUI, it should send lock signal to the LISA to prevent its uninstallation/update by external LISA's API client (eg. DAC Manager) during application active state. If lock request initiated by AWC succeeds application can be started, otherwise return error will be sent to the caller (MainUI) that application is in currently being processed (uninstall) by LISA.

Both scenarios and API change are described below.

API Extension

When LISA's client (DAC Manager, UI) will request to uninstall application which is currently used (locked) by AWC following error will be returned:

{
  "code": 1009,
  "message": "ERROR_APP_ACTIVE"
}

Lock/Unlock calls should be used exclusively by AWC (for now, maybe other use cases will show up which require locking by DAC Manager eg batching) just before transition to start and after transition to stop of the DAC application.

If AWC will try to activate (lock) application during ongoing uninstallation procedure, following error will be returned

{
  "code": 1010,
  "message": "ERROR_APP_UNINSTALLING"
}

By calling getLockInfo caller can receive more details about current lock owner and reason (for now there will be only 2 lisa and awc).

call getLockInfo from AWC → { "owner": "lisa", "reason": "uninstalling" }
call getLockInfo z DACM/UI -> { "owner": "awc", "reason": "active" }

API Schema

LISA API Extension JSON-RPC2.0 Schema

{
  "$schema": "interface.schema.json",
  "jsonrpc": "2.0",
  "info": {
    "title": "Lisa API",
    "class": "Lisa",
    "description": "Lisa JSON-RPC interface",
    "version": "0.0.2"
  },
  "common": {
    "$ref": "common.json"
  },
  "methods": {
    "lock": {
      "summary": "Lock application",
      "description": "Lock and take control over application state until unlock is called",
      "params": {
        "type": "object",
        "properties": {
          "type": {
            "description": "Application type (mime-type)",
            "type": "string",
            "example": "application/vnd.rdk-app.dac.native"
          }, 
          "id": {
            "description": "id of the application, assumed reverse domain name notation, the id should match the [ASMS application id](https://wikiprojects.upc.biz/display/SPARK/ASMS+API+specification)",
            "type": "string",
            "example": "com.libertyglobal.app.awesome"
          },
          "version": {
            "description": "version of the application",
            "type": "string",
            "example": "1.0.0"
          },
          "owner": {
            "description": "Owner of the lock",
            "type": "string",
            "example": "awc"
          },
          "reason": {
            "description": "Reason for the lock",
            "type": "string",
            "example": "active"
          }
        },
        "required": [
          "type",
          "id",
          "version"
        ]
      },
      "result": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string",
            "example": "a76a9ad56769634dbbc9c54bac15ddb9"
          }
        },
        "required": [
          "handle"
        ]
      },
      "errors": [
        {
          "description": "WrongParams",
          "code": 1001,
          "message": "Request not accepted because of wrong parameters"
        },
        {
          "description": "Initializing",
          "code": 1004,
          "message": " LISA is performing initialization, wait for operationStatus event"
        },
        {
          "code": 1009,
          "message": "ERROR_APP_ACTIVE"
        },
        {
          "code": 1010,
          "message": "ERROR_APP_UNINSTALLING"
        }
      ]
    },
    "unlock": {
      "summary": "Unlock application",
      "description": "Unlock application and make it available to be used by other components",
      "params": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string",
            "example": "a76a9ad56769634dbbc9c54bac15ddb9"
          }
        },
        "required": [
          "handle"
        ]
      },
      "result": {
        "type": "object",
        "properties": {}
      },
      "errors": [
        {
          "description": "WrongParams",
          "code": 1001,
          "message": "Request not accepted because of wrong parameters"
        },
        {
          "description": "Initializing",
          "code": 1004,
          "message": " LISA is performing initialization, wait for operationStatus event"
        },
        {
          "description": "WrongHandle",
          "code": 1007,
          "message": "The handle is not correct, e.g. the operation has finished."
        }
      ]
    },
    "getLockInfo": {
      "summary": "Get lock details",
      "description": "Returns info about lock owner and lock reason",
      "params": {
        "type": "object",
        "properties": {
          "type": {
            "description": "Application type (mime-type)",
            "type": "string",
            "example": "application/vnd.rdk-app.dac.native"
          },  
          "id": {
            "description": "id of the application, assumed reverse domain name notation, the id should match the [ASMS application id](https://wikiprojects.upc.biz/display/SPARK/ASMS+API+specification)",
            "type": "string",
            "example": "com.libertyglobal.app.awesome"
          },
          "version": {
            "description": "version of the application",
            "type": "string",
            "example": "1.0.0"
          }
        },
        "required": [
          "type",
          "id",
          "version"
        ]
      },
      "result": {
        "type": "object",
        "properties": {
          "owner": {
            "description": "Owner of the lock",
            "type": "string",
            "example": "awc"
          },
          "reason": {
            "description": "Reason for the lock",
            "type": "string",
            "example": "active"
          }
        }
      },
      "errors": [
        {
          "description": "WrongParams",
          "code": 1001,
          "message": "Request not accepted because of wrong parameters"
        },
        {
          "description": "Initializing",
          "code": 1004,
          "message": " LISA is performing initialization, wait for operationStatus event"
        },
        {
          "description": "WrongHandle",
          "code": 1007,
          "message": "The handle is not correct, e.g. the operation has finished."
        }
      ]
    }
  },
  "events": {
    "operationStatus": {
      "summary": "Completion of asynchronous operation.",
      "description": "Notification sent on the completion of asynchronous operation.",
      "params": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string",
            "example": "4c4712a4141d261ec0ca8f9037950685"
          },
          "operation": {
            "description": "Operation producing the event (Installing, Uninstalling)",
            "type": "string",
            "example": "Installing"
          },
          "type": {
            "description": "Application type (mime-type)",
            "type": "string",
            "example": "application/vnd.rdk-app.dac.native"
          },  
          "id": {
            "description": "id of the application, assumed reverse domain name notation, the id should match the [ASMS application id](https://wikiprojects.upc.biz/display/SPARK/ASMS+API+specification)",
            "type": "string",
            "example": "com.libertyglobal.app.awesome"
          },
          "version": {
            "description": "version of the application",
            "type": "string",
            "example": "1.0.0"
          },
          "status": {
            "description": "Status of the operation (Success, Failed, Progress, Cancelled)",
            "type": "string",
            "example": "Success" 
          },
          "details": {
            "type": "string",
            "example": "Downloaded 2342 KB, unpacked 3233 KB"
          }
        },
        "required": [
          "handle",
          "operation",
          "type",
          "id",
          "version",
          "status"
        ]
      }
    }
  }
}

API Description

Version

Version: 0.0.2

Description

Lisa JSON-RPC interface.

Methods

Name	Type	Description
params	object
params.type	string	Application type (mime-type)
params.id	string	id of the application, assumed reverse domain name notation, the id should match the ASMS application id
params.version	string	version of the application
params?.owner	string	<sup>(optional)</sup> Owner of the lock
params?.reason	string	<sup>(optional)</sup> Reason for the lock (must be one of the following: active, installing, uninstalling)

Result

Name	Type	Description
result	object
result.handle	string

Errors

Code	Message	Description
1001	`Request not accepted because of wrong parameters`	WrongParams
1004	`LISA is performing initialization, wait for operationStatus event`	Initializing
1009	`ERROR_APP_ACTIVE`
1010	`ERROR_APP_UNINSTALLING`

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Lisa.1.lock",
    "params": {
        "id": "com.libertyglobal.app.awesome",
        "version": "1.0.0",
        "owner": "awc",
        "reason": "active"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "handle": "a76a9ad56769634dbbc9c54bac15ddb9"
    }
}

Name	Type	Description
params	object
params.handle	string

Result

Name	Type	Description
result	object

Errors

Code	Message	Description
1001	`Request not accepted because of wrong parameters`	WrongParams
1004	`LISA is performing initialization, wait for operationStatus event`	Initializing
1007	`The handle is not correct, e.g. the operation has finished.`	WrongHandle

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Lisa.1.unlock",
    "params": {
        "handle": "a76a9ad56769634dbbc9c54bac15ddb9"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {}
}

Name	Type	Description
params	object
params.type	string	Application type (mime-type)
params.id	string	id of the application, assumed reverse domain name notation, the id should match the ASMS application id
params.version	string	version of the application

Result

Name	Type	Description
result	object
result?.owner	string	<sup>(optional)</sup> Owner of the lock
result?.reason	string	<sup>(optional)</sup> Reason for the lock (must be one of the following: active, installing, uninstalling)

Errors

Code	Message	Description
1001	`Request not accepted because of wrong parameters`	WrongParams
1004	`LISA is performing initialization, wait for operationStatus event`	Initializing
1007	`The handle is not correct, e.g. the operation has finished.`	WrongHandle

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Lisa.1.getLockInfo",
    "params": {
        "id": "com.libertyglobal.app.awesome",
        "version": "1.0.0"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "owner": "awc",
        "reason": "active"
    }
}

Notifications

Notifications are autonomous events, triggered by the internals of the implementation, and broadcasted via JSON-RPC to all registered observers.

Name	Type	Description
params	object
params.handle	string
params.operation	string	(Installing, Uninstalling)
params.type	string	Application type (mime-type)
params.id	string	id of the application, assumed reverse domain name notation, the id should match the ASMS application id
params.version	string	version of the application
params.status	string	(Success, Failed, Progress, Cancelled)
params?.details	string	<sup>(optional)</sup>

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.1.operationStatus",
    "params": {
        "handle": "4c4712a4141d261ec0ca8f9037950685",
        "operation": "Installing",
        "type": "dac", 
        "id": "com.libertyglobal.app.awesome",
        "version": "1.0.0",
        "status": "Success",
        "details": "Downloaded 2342 KB, unpacked 3233 KB"
    }
}

RDK Resources

[*RDK Preferred*]

[RDK Conferences]

Archives

LISA API Extension (Locking mechanism)

Overview

Design

API Extension

API Schema

API Description

Activity Diagram

Client initiated uninstallation

AWC Start/Stop

Sequence Diagram

AWC DAC registry Initialization and Update

DAC Background Manager installation sequence

DAC Background Manager uninstallation sequence

AWC Start DAC Application

AWC Stop DAC Application

[RDK Preferred]