# spongeRedis

**Repository Path**: du-hanlin/spongeRedis

## Basic Information

- **Project Name**: spongeRedis
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-08-24
- **Last Updated**: 2024-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 信息高铁Sponge及GUID设计

<p align="right"> 先进计算机系统研究中心 系统软件组 杜翰霖</p>

&nbsp;

# 1 Sponge 逻辑设计

## 1.1 Sponge 功能1 - **接入资源注册与管理**

### 1) **设备注册方法** register

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| register | info | GUID | 为接入信息高铁的资源注册，并分发GUID |


>   /**  
      * 在黑板中注册一个新设备  
      * @param info: 设备标识信息  
      * @return ID: 信息高铁中的设备ID  
      */  
    String register(String info);  


&nbsp;

* 说明  
    接入信息高铁的资源的管理结构，Sponge系统和ID系统连接的关键方法。  

    该方法发现接入信息高铁的资源，并将其注册进数据库，供Octopus系统进行资源测调管理；该方法接收资源的标识信息，并调用GUID生成方法生成该资源所属的唯一标识GUID。

&nbsp;

* 参数 `info`：包含接入资源身份标识信息的JSON字符串，示例如下：

    ```json
    {"type":"physical_device","identity_info":"11:22:33:44:55:66+00000-AAAAA-22222","other_info":""}
    ```  

    上面的JSON字符串 **不带换行符** ，传入时必需和可选的字段如下所示：

    ```json
    {   
        "type":"xxx",            //*必需，接入对象类型，只能写特定的名称，见第2节
        "identity_info":"xx",    //*必需，接入对象的唯一标识信息，传入规则见第2节
        "other_info":"",         // 可为空，接入时，希望Sponge记录的其他信息，格式为json字符串
    }  

    ```

&nbsp;

* 返回值： `ID`  

    由 Sponge 调用GUID生成功能生成的 ID，该ID与调用本方法注册进 Sponge 的资源一一对应，**具有唯一性，在该设备彻底注销前不再改变**。  
    生成失败时，返回空串。

&nbsp;

### 2) 设备注销方法 delete  

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| delete | GUID | status | 从Sponge中删除已注册的资源 |

>   /**  
     * 在黑板中删除一个新设备  
     * @param ID 信息高铁中的设备ID  
     * @return 执行状态  
     */  
    InteractiveStatusEnum delete(String ID);

&nbsp;

* 说明  
    删除已注册资源的方法。  

    该方法在对应资源彻底不再使用信息高铁时，从Sponge中删除对应资源。除非是硬件原因导致的不再使用，否则不建议调用本方法。

&nbsp;

* 参数: `GUID`  

    设备 ID，由上述注册函数得到。如果不再特别强调，其他相关方法的参数也唯一是该 ID。

&nbsp;
    
* 返回值: `status`

    函数执行状态，字段类型为枚举类：

    ```java
    enum InteractiveStatusEnum {  
        Success,            // 执行成功
        IDNotFound,         // ID未找到
        IDAlreadyExist,     // ID重复存在

        Activate,           // 不在本方法使用
        Inactivate,         // 不在本方法使用
        NotExist,           // 不在本方法使用

        Unknown;            // 未知错误
    }
    ```
    如果不再特别强调，其他相关方法的返回值也是该枚举类

&nbsp;

### 3) 设备心跳方法 renewal

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| renewal | GUID | status | 向Sponge中对应资源发送心跳信息 |

>   /**   
     * 已存在设备的心跳   
     * 建议续约时间: 2s  
     * @param ID 信息高铁中的设备ID  
     * @return 执行状态  
     */  
    InteractiveStatusEnum renewalDevice(String ID);

&nbsp;

* 说明

    告知 Sponge 该资源处于活跃状态  

    由于不确定接入Sponge的资源是否长期活跃，每个接入资源在Sponge中都拥有一个TTL（默认值为5s）。心跳方法需要被反复调用，以确认该设备的活跃状态。建议在设备初始化时，在线程中循环调用该方法。该循环调用与Octopus-agent相关联。

&nbsp;

### 4) 断线后重连方法 reconnect

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| reconnect | GUID | status | 在设备重新连接后，向Sponge发送重连请求，使其重新变为活跃状态 |

>   /**  
     * 重新连接到黑板  
     * @param ID 信息高铁中的设备ID  
     * @return 执行状态  
     */  
    InteractiveStatusEnum reconnect(String ID);


&nbsp;

* 说明

    断线后Sponge内对应设备会由于收不到心跳而变为断线状态，需要通过本方法重连。‘

&nbsp;


## 1.2 Sponge 功能2 - **资源查询和统计**

&nbsp;

### 1) 指定资源查询

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| getResource | infoType | resource | 查询所请求的资源 |

>   /**   
     * 查询所请求的资源   
     * @param infoType 希望查询的资源类别   
     * @return 资源信息Json字符串  
     */  
    String getResource(String infoType);

&nbsp;

* 说明  
    根据传入的请求，查询所需资源。  

    不同种类的查询请求（如查询指定ID的资源是否可用，与查询指定种类的可用资源列表），会根据传入的infoType进行分类。

&nbsp;

* 参数: `infoType`  

    查询请求类别，有限的json字符串，key限定为下列之一：

    ```java
        "type"       // 对应于第2节-deviceInfo数据段-设备主类型 所规定的type
        "ID"         // 已知的资源ID
        "keyword"    // 对应于注册时，“other_info”所传入的json键值对的key。当发现key匹配时，成功返回
    ```

&nbsp;
    
* 返回值: `resource`

    对于不同的参数，有不同种类的返回值

    ```java
        "type":ArrayList<ID>       // 返回对应类别下所有资源的ID数组
        "ID":infoJson              // 返回对应资源所有信息的Json
        "keyword":Map<ID, info>    // 返回匹配到key的所有ID和对应key下的value值
    ```

&nbsp;

### 2) 资源、命令信息统计

&nbsp;

| 方法名称 | 参数 | 返回值 | 功能 |
| ----- | ----- | ----- | ----- |
| renewal | ID, info | statistics | 统计传过的资源命令信息 |

>   /**   
     * 统计传过的资源命令信息   
     * @param ID GUID   
     * @param info 当前命令、资源信息   
     * @return 总资源、命令统计数据  
     */  
    String renewal(String ID, String info);

&nbsp;

* 说明  
    接收当前的资源和命令信息，统计后返回相关联的所有信息统计数据  

    本方法重载了心跳接口 `renewal`，在上一次心跳起到本次心跳止，如果当前资源（边端或云端）向其他人发送了资源或命令信息，则将其信息类别和发送数目传给Sponge，供Sponge进行统计，并返回统计结果

&nbsp;

* 参数: `info`  

    上一次心跳起到本次心跳止，当前资源向其他人发送资源、命令信息的信息类别和发送数目。
    json字符串，包含以下内容
    ```json
    {
        "id": "guid",                   // 调用者的GUID
        "time_stamp": 1234567890123,    // 当前时间戳
        "state": 0,                     // 资源当前状态
        "message_count": 10,            // 两心跳间的资源信息数
        "control_count": 2              // 两心跳间的控制信息数
    }
    ```

&nbsp;
    
* 返回值: `statistics`

    总的信息统计。json字符串，包含以下内容
    ```json
    {
        "id": "guid",                   // 调用者的GUID
        "time_stamp": 1234567890123,    // 当前时间戳
        "state": 0,                     // 资源当前状态
        "message_count": 10,            // 资源信息总数
        "control_count": 2              // 控制信息总数
    }
    ```

&nbsp;

# 2 ID 唯一性设计

&nbsp;

### ID唯一性保证：使用**deviceInfo**数据段进行唯一身份标识

&nbsp;

## 2.1 deviceInfo 数据段

| 示例 | 00-16-EA-AE-3C-40 | 00-16-EA-AE-3C-44 | 00-00 | 99-00-11-22 |
| ----- | -----| ----- | ----- | ----- |
| 字段含义 | 设备主类型号 | 设备序列号 | 资源类别 | 资源号 |
| 长度 | 6byte | 6byte | 2byte | 4byte |
| 备注 | | | 0:云; 1:边; 2:端 | 比如，端：0电机;1摄像头; |

- 设备主类型号（原设备提供商编号）

        设备注册进入信息高铁时，根据设备的类型（如：总线、容器、可移动设备、不可移动设备等）进行分类，每一种主类型拥有一个特定的描述符，可以通过查描述符表得到其类型名称。
        这一信息应当由设备传给Sponge控件。

- 设备序列号（原设备提供商内部编号）

        设备序列号，即设备注册进Sponge时的序列号，由Sponge给出，按照注册顺序进行排序。
        主类型号和序列号可以进一步划分，使用不同的数位代表不同设备子类型。

- 资源类别

        分为3类，即云、边、端，根据设备自身的特性给出，由设备传给Sponge控件。

- 资源号（非0）

        主要为附属设备的号码，如小车上的摄像头、超声测距仪等。
        对于注册时，该段为0，表示整体设备。
        对于传输信息时，Sponge根据设备所拥有的附属设备，分配资源号。分配的资源号需要记录进资源类别表，这一信息同样需要设备通过附加信息段的方式告诉Sponge。
        一般而言，不同设备的同种资源拥有相同的资源号。

&nbsp;

## 2.2 deviceInfo信息分配方法

- 说明  
    info字段是JSON字符串，其格式符合标准的JSON字符串格式。建议调用者用JSON.toJsonString()方法生成
    当前设计为第一阶段的字段设计，后续还会进行更改，主要是“类型”字段的变化，注意核查

1. 字段示例

    ```json
    {
        "type":"physical_device",
        "identity_info":"11:22:33:44:55:66+00000-AAAAA-22222",
        "other_info":""
    }
    ```

2. 字段类型

    - 注册者类型  `"type"`

        变量类型：字符串（限定变量值）  

        注册者的类型。注册者传递时只能传递指定的值  

    - 注册者唯一标识信息  `"identity_info"`

        变量类型：字符串   
        用于注册者标识自身唯一性，源自注册者自带的身份信息。包括三段，分别是身份标识1、身份标识2和其他身份标识。**三段之间用"+"号相连（见字段示例）**

        | JSON key | mark_1 | mark_2 | mark_others |
        | -----| ----- | -----| ----- |
        | 说明 | 身份标识1 | 身份标识2 | 其他身份标识 |
        | 示例 | 11:22:33:44:55:66 | 00000-AAAAA-22222 | - |

    - 其他信息 `"other_info"`
    
&nbsp;

### 1） 设备主类型号
- 说明  

    设备主类型的标识符，传输关键字：`"type"`

    最终可以使用的主类型名称：

    `Nervous`  

    `Car`  
    `Aircraft`  
    `PC`  
    `Server`  
    `Mobile`  

    `Docker`  
    `MicroService`  
    `Center`

    `Others`  

- 示例：
    ```json
    {
        "type":"Nervous"
    }
    Sponge处理得到主类型号：1
    ```

&nbsp;

### 2） 设备序列号

&nbsp;

- 说明 

    设备序列号为一组从1开始的、由Sopnge负责分发的标识符。对于每一种设备主类型，设备序列号标识了唯一一个设备。设备序列号的分配依据是设备本身固有的身份标识

- 在设计deviceInfo字段时，应当按照以下信息段映射得到设备序列号：

    | 设备标识 | 身份标识1 | 身份标识2 | 其他身份标识 |
    | ----- | -----| ----- | -----|
    | 例：PC设备 | 设备ID号（*不是GUID*，由厂商给出，可以查询到） | 产品ID号（与硬件相关，可以查询到） | 无 |

    该示例中，如果传入的身份标识１和身份标识２，在已有的设备信息存储中没有重复，则说明该设备是新设备，给其分配一个还没有使用的非零序列号

- 例：实体设备  
    | 身份标识1 | 身份标识2 | 其他身份标识 |
    | -----| ----- | -----|
    | 设备ID号（或MAC地址） | 产品ID号（或CPUID号） | 无 |
    
- 例：服务
    | 身份标识1 | 身份标识2 | 其他身份标识 |
    | -----| ----- | -----|
    | 服务IP地址 | 服务端口号 | 无 |    
    
    （以上方法要求服务每次启动时不更换IP地址和端口）