Package com.inductiveautomation.perspective.gateway.property

Class PropertyTree

  • public class PropertyTree
extends java.lang.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 Detail

      • PropertyTree

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

    • Method Detail

      • subscribe

        public PropertyTree.Subscription subscribe​(java.lang.String pathString,
                                           java.util.Set<Origin> acceptableOrigins,
                                           java.util.function.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​(java.lang.String pathString,
                                           java.util.Set<Origin> acceptableOrigins,
                                           java.util.function.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,
                                           java.util.Set<Origin> acceptableOrigins,
                                           java.util.function.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,
                                           java.util.Set<Origin> acceptableOrigins,
                                           java.util.function.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

      • 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)

      • read

        public java.util.Optional<QualifiedValue> read​(java.lang.String pathString)

      • writeAll

        public void writeAll​(com.inductiveautomation.ignition.common.gson.JsonObject writes,
                     Origin origin,
                     java.lang.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​(java.lang.String pathString,
                  com.inductiveautomation.ignition.common.gson.JsonElement element,
                  Origin origin,
                  java.lang.Object source)

      • write

        public void write​(java.lang.String pathString,
                  QualifiedValue value,
                  Origin origin,
                  java.lang.Object source)

      • remove

        public void remove​(JsonPath path,
                   Origin origin,
                   java.lang.Object source)

      • hasProperty

        public boolean hasProperty​(java.lang.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 java.util.List<java.lang.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​(java.lang.String type,
                                                                                               QualityCode quality,
                                                                                               long timestamp)

      • isQualifiedValueMap

        public static boolean isQualifiedValueMap​(@Nullable
                                          java.lang.Object object)

      • isQualifiedValueArray

        public static boolean isQualifiedValueArray​(java.lang.Object object)