OpenTCS学习笔记（一）——为模型中的元素添加新的属性

本文详细介绍了如何在OpenTCS中为模型元素添加新属性，并确保这些属性在Kernel和PlantOverView之间同步。通过修改核心代码和XML架构，实现了自定义属性的存储和读取。

OpenTCS学习笔记（一）——为模型中的元素添加新的属性（本文持续更新中）

openTCS是一个用于自动车辆的控制系统/车队管理软件，主要用于协调AGV任务，软件是java开发。在进行建模过程中，我们会根据自己的需要，为模型元素增加新的属性，并使其可视化。不过官方文档对于如何为模型元素添加新属性并没有讲解，所以我就阅读了源码，下面讲讲基本操作：

OpenTCS源码下载地址：http://www.opentcs.org/en/download.html
我下载的是4.18.0版本

数据结构

先来谈谈模型中元素的数据结构，下面以点（Point）为例，其他元素类似。我们需要用到的数据结构如下：（加上了我的一些个人理解，还在学习，不一定正确哈）

Point ，点作为一种资源的存储结构，在Kernel中访问点的时候，此类结构会被调用；
PointModel，一般与上述的Point结构绑定，用于创建点在PlantOverView中的模型实例；
PointAdapter ，将Point与PointModel进行绑定，个人理解是将PlantOverView中建立的模型实例（PointModel）与Kernel中的点资源进行同步，保证用户在可视化界面看到的模型数据与内核读取到的数据是一样的；
PointTO，点在转换过程中的中间产物结构，它的功能（我暂时了解到的）仅为：在向XML文件读取模型或者将模型写入文件时，作为转换的中间产物；
PointCreationTO，如果要将点写入XML文件，我们需要先将它从PointModel转化为PointCreationPO，再转化为PointTO。

实现流程

下面以添加点的z坐标为例，强烈建议在修改源代码之前先备份

一、修改Kernel中的点结构

Kernel中的点结构也就是Point，我们需要在Point类中，添加我们想要的新成员，此处我们添加z轴坐标，并添加相对应的构造方法和以及对z轴坐标的操作方法（获取、修改）

不过巧合的是，OpenTCS本身的Point类是保留了z轴坐标的，所以在这里不需要对Point类进行改动，如果是其他新成员则要注意添加对应的操作方法和构造方法，此外还需要修改其clone()方法，比如将clone()方法里调用的构造方法换成包含有新成员的构造方法（这一点很重要），至于为什么重要？我们下面再具体讲。

二、修改PlantOverView中的点结构

也就是修改建模工厂总的点模型，这里面就涉及比较多的类了

1.修改PointModel

PointModel是点在建模工厂中的主要表现结构，我们在PlantOverView中看到的一个点的信息，都是来自于PointModel

修改步骤：在点的模型中我们不需要添加成员，因为Model类中一般直接调用了属性创建函数，如下：

 public PointModel() {
   
   
    createProperties();
  }

所以我们只需要创建一个子方法（用来创建我们需要的属性），再在属性创建函数中调用这个子方法就行了，我这里直接参照了X,Y坐标的子方法，比如：

子方法：

  public CoordinateProperty getPropertyModelPositionZ() {
   
   
  return (CoordinateProperty) getProperty(MODEL_Z_POSITION);
}

属性创建方法中：

    CoordinateProperty pPosZ = new CoordinateProperty(this,
                                                      DEFAULT_XY_POSITION,
                                                      LengthProperty.Unit.MM);
    pPosZ.setDescription(bundle.getString("pointModel.property_modelPositionZ.description"));
    pPosZ.setHelptext(bundle.getString("pointModel.property_modelPositionZ.helptext"));
    setProperty(MODEL_Z_POSITION, pPosZ);

首先，这里面多了一个新的变量MODEL_Z_POSITION，它其实就是该属性的全局唯一名字,可以理解为该属性的id，但要注意该名字并不是属性显示在可视化界面的名字；我参照X,Y坐标在PositionableModelComponent.java文件中添加了

  /**
   * Key for the Z (model) cordinate.
   */
  public static final String MODEL_Z_POSITION = "modelZPosition";
}

如果是其他的属性，可以根据属性的特性放在对应的文件中，例如：如果是Point特有，则直接在PointModel中添加该字符串即可；但一定要注意该字符串不能与其他已有的属性id重复。

此外，我们可以看到这个坐标属性还创建了该属性对应的描述和帮助文档。这个其实是PlantOverView中，我们鼠标停放在属性栏上时，出现的文字描述以及该属性的名称，如下图：

Alt
我们可以在文件Bundle.properties中添加、修改属性的描述和帮助文档，如下：

locationModel.property_modelPositionZ.description=z-Position (model)
locationModel.property_modelPositionZ.helptext=The z coordinate of the location in the kernel model

这一部分就修改完了

2.修改PointAdapter

修改适配器，因为PointModel类是与Point类保持同步的，我们在Point中增加了新的成员，在PointModel增加了新的属性创建子方法，接下来要做到就是把这个属性创建子方法对应到增加的新成员上，保证两个类是同步的

同步的实现主要是靠updateModelProperties方法和storeToPlantModel方法，前者是将Point里的信息同步到PointModel，后者是将PointModel信息同步到Point里，我们需要做的就是将Point里面的成员对应到PointModel的属性创建子方法，因此参照里面原有的代码，将Point里的新成员与PointModel的属性创建子方法对应起来，如下：

updateModelProperties方法新增：

    model.getPropertyModelPositionZ().setValueAndUnit(point.getPosition().getZ(),
                                                      LengthProperty.Unit.MM);

storeToPlantModel方法不太一样，它调用了其他子方法来获取PointModel中的信息以同步到Point中，因此我们不仅要修改storeToPlantModel方法，还要增加或者修改其调用的子方法；
由于我只是要新增z坐标，原本的storeToPlantModel方法只是同步了X和Y坐标，因此我需要先修改子方法getKernelCoordinates，如下：

getKernelCoordinates方法：

  private Triple getKernelCoordinates(PointModel model) {
   
   
    return convertToTriple(model.getPropertyModelPositionX(),
                           model.getPropertyModelPositionY(),
                           model.getPropertyModelPositionZ());
  }

然后在storeToPlantModel方法中，我这个例子基本不用修改，不过如果是其他的新属性，则要考虑修改；
此外，注意PointAdapter中还有一个updateModelLayoutProperties方法，顾名思义，这是用于同步模型的布局（layout）属性的，布局属性也就是一些可视化的属性，比如点在布局中的坐标（区别于点的模型坐标）