Package com.inductiveautomation.perspective.gateway.property

Class PropertyTree

java.lang.Object
com.inductiveautomation.perspective.gateway.property.PropertyTree
public class PropertyTree extends Object

This class represents a tree structure of properties. Based on the JSON format, the structure is built up of nodes that are:

  • Name/Value pairs, where the name is a string and the value is another node in the tree
  • Ordered list of nodes, where each node has an index starting with zero (an array)
  • A primitive value, which may be null, string, or number.

Each node in the tree also contains quality and timestamp information. Therefore, any node may be read as a QualifiedValue.

Any element contained within this structure is represented by a path. The format of the path is identical to the javascript expression you would use to reference the element. For example, you could reference a root property with "foo", a sub-property with "foo.bar", an indexed property with "foo.bar[5]" and a property whose name is not a legal javascript identifier with "foo['sub property here']

This tree is observable in two ways:

  1. Interested parties may register a listener for a specific path using subscribe(String, Set, Consumer, boolean). Whenever the value at that path has changed, the listener will receive a PropertyTreeChangeEvent which contains the Origin and a Supplier of the new value as a QualifiedValue.
  2. One may also listen to all changes made to the property collection using subscribeAll(Consumer). This listener will be notified of any changes.

  • Constructor Details

    • PropertyTree

      public PropertyTree(@Nonnull com.inductiveautomation.ignition.common.gson.JsonObject json, @Nonnull ExecutionQueue queue)

    • PropertyTree

      public PropertyTree(@Nonnull com.inductiveautomation.ignition.common.gson.JsonObject json, @Nonnull ExecutionQueue queue, @Nonnull PropertyTreePermissionModel permissionModel)

  • Method Details

    • subscribe

      public PropertyTree.Subscription subscribe(String pathString, Set<Origin> acceptableOrigins, Consumer<PropertyTreeChangeEvent> consumer, boolean coalesce)
      Subscribes to a specific path in the tree. The provided consumer will be called with a PropertyTreeChangeEvent which contains a Supplier that can fetch the QualifiedValue when it changes.
      Parameters:
      pathString - The path to the property to subscribe to
      acceptableOrigins - Set of origins that this listener is interested in
      consumer - The listener that will be called when a change that affects the given path occurs
      coalesce - If true, the listener will be invoked only once for operations that may have generated multiple changes the listener is interested in.
      Returns:
      Object that contains unsubscribe() method to remove this listener

    • subscribe

      public PropertyTree.Subscription subscribe(String pathString, Set<Origin> acceptableOrigins, Consumer<PropertyTreeChangeEvent> consumer)
      Subscribes to a specific path in the tree. The provided consumer will be called with a PropertyTreeChangeEvent which contains a Supplier that can fetch the QualifiedValue when it changes.
      Parameters:
      pathString - The path to the property to subscribe to
      acceptableOrigins - Set of origins that this listener is interested in
      consumer - The listener that will be called when a change that affects the given path occurs
      Returns:
      Object that contains unsubscribe() method to remove this listener

    • subscribe

      public PropertyTree.Subscription subscribe(JsonPath path, Set<Origin> acceptableOrigins, Consumer<PropertyTreeChangeEvent> consumer, boolean coalesce)
      Subscribes to a specific path in the tree. The provided consumer will be called with a PropertyTreeChangeEvent which contains a Supplier that can fetch the QualifiedValue when it changes.
      Parameters:
      path - The JsonPath to the property to subscribe to
      acceptableOrigins - Set of origins that this listener is interested in
      consumer - The listener that will be called when a change that affects the given path occurs
      coalesce - If true, the listener will be invoked only once for operations that may have generated multiple changes the listener is interested in.
      Returns:
      Object that contains unsubscribe() method to remove this listener

    • subscribe

      public PropertyTree.Subscription subscribe(JsonPath path, Set<Origin> acceptableOrigins, Consumer<PropertyTreeChangeEvent> consumer)
      Subscribes to a specific path in the tree. The provided consumer will be called with a PropertyTreeChangeEvent which contains a Supplier that can fetch the QualifiedValue when it changes.
      Parameters:
      path - The JsonPath to the property to subscribe to
      acceptableOrigins - Set of origins that this listener is interested in
      consumer - The listener that will be called when a change that affects the given path occurs
      Returns:
      Object that contains unsubscribe() method to remove this listener

    • subscribeAll

      public void subscribeAll(Consumer<PropertyTreeChangeEvent> listener)

    • merge

      public void merge(com.inductiveautomation.ignition.common.gson.JsonObject tree)
      Merges the given tree's values and structure with this tree. New structure and values from the given tree may be added to this one. No changes fired.

    • merge

      public void merge(com.inductiveautomation.ignition.common.gson.JsonObject tree, boolean prune, boolean fireChange)
      Merge, with options.
      Parameters:
      prune - If true, existing nodes that aren't in the new merge tree will be removed
      fireChange - If true, the change listeners will be notified of the changes due to the merge.

    • reset

      public void reset(com.inductiveautomation.ignition.common.gson.JsonObject tree)

    • getQueue

      public ExecutionQueue getQueue()

    • read

      public Optional<QualifiedValue> read(String pathString)

    • read

      public Optional<QualifiedValue> read(JsonPath path)

    • writeAll

      public void writeAll(com.inductiveautomation.ignition.common.gson.JsonObject writes, Origin origin, Object source)
      Performs multiple writes into this property tree
      Parameters:
      writes - An object containing paths of properties to write to and the values to write to them
      origin - where the write came from

    • write

      public void write(String pathString, com.inductiveautomation.ignition.common.gson.JsonElement element, Origin origin, Object source)

    • write

      public void write(String pathString, QualifiedValue value, Origin origin, Object source)

    • write

      public void write(JsonPath path, QualifiedValue value, Origin origin, Object source)

    • remove

      public void remove(JsonPath path, Origin origin, Object source)

    • hasProperty

      public boolean hasProperty(String path)
      Parameters:
      path - Path to look for - should be parseable by JsonPath.parse(java.lang.String)
      Returns:
      true if there is a property for the given path

    • getRootKeys

      public List<String> getRootKeys()

    • toJson

      public com.inductiveautomation.ignition.common.gson.JsonObject toJson()
      Creates a JSON representation of the values in this property tree, encoded in our $-qualified format. Will not include properties marked as access=PRIVATE

    • newDollarQualifiedObject

      public static com.inductiveautomation.ignition.common.gson.JsonObject newDollarQualifiedObject(String type, QualityCode quality, long timestamp)

    • isQualifiedValueMap

      public static boolean isQualifiedValueMap(@Nullable Object object)

    • isQualifiedValueArray

      public static boolean isQualifiedValueArray(Object object)