data_model.h

浏览该文件的文档.

#ifndef AUBO_SCOPE_DATA_MODEL_H
#define AUBO_SCOPE_DATA_MODEL_H
 
#include <stdint.h>
#include <string>
#include <vector>
#include <set>
 
#include <aubo_caps/domain/feature/feature.h>
#include <aubo_caps/domain/variable/variable.h>
#include <aubo_caps/domain/tcp/tcp.h>
#include <aubo_caps/domain/io/io.h>
#include <aubo_caps/domain/waypoint/waypoint.h>
#include <aubo_caps/domain/payload/payload.h>
#include <aubo_caps/domain/value/expression/expression.h>
 
namespace arcs {
namespace aubo_scope {
ARCS_CLASS_FORWARD(DataModel);
 
/**
 * \chinese
 * 数据模型
 * 此接口用于存储和管理表示当前配置的数据，例如 {@link ProgramNodeContribution}
 * 或 {@link InstallationNodeContribution} 的配置。提供了在字典中添加、删除、获取
 * 和修改值的方法。
 *
 * 为已使用的键设置新值将覆盖当前值。无论值的类型如何都会发生（例如，在键
 * <i>myBool</i> 下存储值 <code>true</code>，之后又在同一键下存储一个
 * <code>Angle</code> 对象，将会用提供的 <code>Angle</code> 对象覆盖
 * <code>true</code> 值）。
 *
 * 每个 AuboCap 安装画面都有一个底层的 <code>DataModel</code> 对象。该对象随每个
 * AuboScope 安装一起保存和加载。
 *
 * 同样，每个贡献的程序节点实例都有一个底层的 <code>DataModel</code>
 * 对象。该对象随节点所在程序一起保存和加载。基于 HTML 的程序节点贡献中，对
 * <code>DataModel</code> 对象的所有修改都支持撤销/重做操作。基于 Qt 的 AuboStudio
 * 插件必须使用 {@link UndoRedoManager} 将更改记录到撤销/重做栈中。
 *
 * 检索对象时，键和对象类型都必须与之前存储的匹配。这意味着如果使用键
 * <i>myAngle</i> 存储了一个 <code>TCP</code> 对象，然后尝试使用键 <i>myAngle</i>
 * 通过 {@link #get(std::string key, Angle default_value)} 检索它，将不会返回存储
 * 的值，因为类型不匹配。相反，将返回提供的 <code>default_value</code>。
 * \endchinese
 * \english
 * DataModel
 * This interface is used for storing and managing data that represents the
 * current configuration of, e.g. a
 * {@link ProgramNodeContribution} or {@link InstallationNodeContribution}.
 * Methods for adding, removing, retrieving and changing values in a dictionary
 * are provided.
 *
 * Setting a new value for a key already in use, will overwrite the current
 * value with the new value. This happens regardless of the type of value (e.g.
 * storing the value <code>true</code> under the key <i>myBool</i>
 * and afterwards storing an <code>Angle</code> object under the same key will
 * overwrite the value <code>true</code> with the provided <code>Angle</code>
 * object).
 *
 * A auboCap installation screen has an underlying <code>DataModel</code>
 * object. That object is saved and loaded along with each AuboScope
 * installation.
 *
 * Similarly, each contributed program node instance has an underlying
 * <code>DataModel</code> object. That object is saved and loaded along with the
 * program where the node occurs. Undo/redo actions are supported for all
 * modifications to the <code>DataModel</code> object in HTML-based program node
 * contributions. Qt-based aubo_studio plugins must use the {@link
 * UndoRedoManager} to record the changes on the undo/redo stack.
 *
 * When retrieving an object, both key and object type must match what was
 * previously stored. This means that if a
 * <code>TCP</code> object was stored using the key <i>myAngle</i>, then
 * attempting to retrieve it using
 * {@link #get(std::string key, Angle default_value)} with the key
 * <i>myAngle</i> will not return the stored value, since the types do not
 * match. Instead the provided <code>default_value</code> will be returned.
 * \endenglish
 *
 */
class ARCS_ABI_EXPORT DataModel
{
public:
    DataModel(DataModel &f);
    DataModel(DataModel &&f);
    ~DataModel();
 
    /**
     * \chinese
     * 将<code>bool</code>值赋给指定键。
     *
     * @param key 数据模型中的键（不可为<code>null</code>或空<code>std::string</code>）。
     * @param value 赋给键的值。
     *
     * @throws IllegalArgumentException 如果键为<code>null</code>或空<code>std::string</code>。
     * @throws IllegalStateException 如果在Qt-based AuboCap程序节点中调用时不在
     * {@link UndoableChanges}范围内（另见{@link UndoRedoManager}）。
     * \endchinese
     * \english
     * Assign a <code>bool</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, bool value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>bool</code>值。
     *
     * @param key 数据模型中的键。
     * @param default_value 键不存在时返回的值。
     * @return 赋给键的值。如果不存在，返回default_value。
     * \endchinese
     * \english
     * Get the <code>bool</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    bool get(const std::string &key, bool default_value) const;
 
    /**
     * \chinese
     * 将<code>int</code>值赋给指定键。
     *
     * @param key 数据模型中的键。
     * @param value 赋给键的值。
     *
     * @throws IllegalArgumentException 如果键为<code>null</code>或空字符串。
     * @throws IllegalStateException 如果不在{@link UndoableChanges}范围内调用。
     * \endchinese
     * \english
     * Assign an <code>int</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, int value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>int</code>值。
     *
     * @param key 数据模型中的键。
     * @param default_value 键不存在时返回的值。
     * @return 赋给键的值。
     * \endchinese
     * \english
     * Get the <code>int</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    int get(const std::string &key, int default_value) const;
 
    /**
     * \chinese
     * 将<code>long</code>值赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>long</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, long value);
    void set(const std::string &key, uint64_t value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>long</code>值。
     * \endchinese
     * \english
     * Get the <code>long</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    long get(const std::string &key, long default_value) const;
    uint64_t get(const std::string &key, uint64_t default_value) const;
 
    /**
     * \chinese
     * 将<code>float</code>值赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>float</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, float value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>float</code>值。
     * \endchinese
     * \english
     * Get the <code>float</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    float get(const std::string &key, float default_value) const;
 
    /**
     * \chinese
     * 将<code>double</code>值赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>double</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, double value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>double</code>值。
     * \endchinese
     * \english
     * Get the <code>double</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    double get(const std::string &key, double default_value) const;
 
    /**
     * \chinese
     * 将<code>std::string</code>值赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>std::string</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::string &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>std::string</code>值。
     * \endchinese
     * \english
     * Get the <code>std::string</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::string get(const std::string &key,
                    const std::string &default_value) const;
    /**
     * \chinese
     * 将<code>Variable</code>值赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>Variable</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, VariablePtr value);
    void set(const std::string &key, ExpressionPtr value);
    void set(const std::string &key, PayloadPtr value);
    void set(const std::string &key, IoPtr value);
    void set(const std::string &key, WaypointPtr value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>Variable</code>值。
     * @return 赋给键的值。
     * \endchinese
     * \english
     * Get the <code>Variable</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    VariablePtr get(const std::string &key, VariablePtr default_value) const;
    ExpressionPtr get(const std::string &key,
                      ExpressionPtr default_value) const;
    PayloadPtr get(const std::string &key, PayloadPtr default_value) const;
    IoPtr get(const std::string &key, IoPtr default_value) const;
    WaypointPtr get(const std::string &key, WaypointPtr default_value) const;
 
    /**
     * \chinese
     * 将<code>bool[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>bool[]</code> as value to the specified key.
     * @param key key in the data model (not <code>null</code>) and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<bool> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>bool[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>bool[]</code> as value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<bool> get(const std::string &key,
                          const std::vector<bool> &default_value) const;
 
    /**
     * \chinese
     * 将<code>int[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>int[]</code> as value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<int> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>int[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>int[]</code> as value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<int> get(const std::string &key,
                         const std::vector<int> &default_value) const;
 
    /**
     * \chinese
     * 将<code>long[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>long[]</code> as value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null} or an empty
     * <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<long> &value);
    void set(const std::string &key, const std::vector<uint64_t> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>long[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>long[]</code> as value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<long> get(const std::string &key,
                          const std::vector<long> &default_value) const;
    std::vector<uint64_t> get(const std::string &key,
                              const std::vector<uint64_t> &default_value) const;
 
    /**
     * \chinese
     * 将<code>float[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>float[]</code> as value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<float> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>float[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>float[]</code> as value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<float> get(const std::string &key,
                           const std::vector<float> &default_value) const;
 
    /**
     * \chinese
     * 将<code>double[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>double[]</code> as value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<double> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>double[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>double[]</code> as value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<double> get(const std::string &key,
                            const std::vector<double> &default_value) const;
 
    /**
     * \chinese
     * 将<code>std::string[]</code>数组赋给指定键。
     * \endchinese
     * \english
     * Assign a <code>std::string[]</code> as value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, const std::vector<std::string> &value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>std::string[]</code>数组。
     * \endchinese
     * \english
     * Get the <code>std::string[]</code> as value assigned to the specified
     * key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    std::vector<std::string> get(
        const std::string &key,
        const std::vector<std::string> &default_value) const;
 
    /**
     * \chinese
     * 将<code>TCP</code>值赋给指定键。
     * \endchinese
     * \english
     *  Assign a <code>TCP</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, TCPPtr value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>TCP</code>值。
     * \endchinese
     * \english
     * Get the <code>TCP value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    TCPPtr get(const std::string &key, TCPPtr default_value) const;
 
    /**
     * \chinese
     * 将<code>Feature</code>值赋给指定键。
     * \endchinese
     * \english
     *  Assign a <code>Feature</code> value to the specified key.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @param value value assigned to key.
     *
     * @throws IllegalArgumentException if the key is <code>null</code> or an
     * empty <code>std::string</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    void set(const std::string &key, FeaturePtr value);
 
    /**
     * \chinese
     * 获取赋给指定键的<code>Feature</code>值。
     * \endchinese
     * \english
     * Get the <code>Feature</code> value assigned to the specified key.
     *
     * @param key key in the data model.
     * @param default_value value to be returned, if key does not exist.
     * @return the value assigned to the key. If not exist, default_value is
     * returned.
     * \endenglish
     */
    FeaturePtr get(const std::string &key, FeaturePtr default_value) const;
 
    /**
     * \chinese
     * 获取数据模型中所有键的集合。
     * @return 键的集合。
     * \endchinese
     * \english
     * Get a set of all the keys in the data model.
     *
     * @return A Set of keys.
     * \endenglish
     */
    std::set<std::string> getKeys() const;
 
    /**
     * \chinese
     * 检查数据模型中是否存在指定键。
     * @param key 数据模型中的键。
     * @return 如果键存在返回<code>true</code>，否则返回<code>false</code>。
     * \endchinese
     * \english
     * Check if a key is present in the data model.
     *
     * @param key key in the data model (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @return <code>true</code>, if key exist, otherwise <code>false</code>.
     * \endenglish
     */
    bool isSet(const std::string &key) const;
 
    /**
     * \chinese
     * 从数据模型中移除一个键值对。
     * @param key 数据模型中的键。
     * @return 成功返回<code>true</code>，否则返回<code>false</code>。
     * @throws IllegalStateException 如果在Qt-based AuboCap程序节点中调用时不在
     * {@link UndoableChanges}范围内。
     * \endchinese
     * \english
     * Remove a key-value pair from the data model.
     *
     * @param key key in the data model  (not <code>null</code> and not an empty
     * <code>std::string</code>).
     * @return <code>true</code>, if succeed, otherwise <code>false</code>.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * program node outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    bool remove(const std::string &key);
 
private:
    friend class DataSwitch;
    DataModel();
    void *d_{ nullptr };
};
 
} // namespace aubo_scope
} // namespace arcs
 
#endif