Package com.inductiveautomation.perspective.gateway.property

Class PropertyReference

  • Direct Known Subclasses:
    DesignerPropertyReference
    public class PropertyReference
extends AbstractLifecycle

    A PropertyReference is a context-aware object that resolves properties between different components within the same parent View, or, more specifically, within each View's root container Component.

    Property references are resolved with respect to the target PerspectiveElement (e.g., the one passed in to the constructor of this class), in order to identify a property that may provide values. In order to fully resolve a property reference and allow for the subscription of property changes, the views must first be fully initialized so that all child components have necessary models.

    These references are a String, and consist of two parts: a Path Prefix,followed by a valid Property Identifier.

    There are 3 types of Path Prefix:

    • Relative- a prefix following familiar linux path formats such as ./ and ../../
    • Absolute- a prefix which resolve the location based from the root view, such as /aContainer/myComponent/
    • Shortcut- a special prefix that allows convenient references to a component's own properties, its parent, or the root view. Does not allow path separators.
    The Prefix is used to determine the location of the component in the view's hierarchy.

    After the prefix comes the Property Identifier. A Property Identifier is the json-like path to a specific property on the target component. The property lives inside one of the component's PropertyTrees. A valid property identifier has three parts, demarcated by '.' in the form <name>.<scope>.<property_identifier>, with the following restrictions:

    • Name
      • begins with a letter or underscore, and may only contain letters, numbers and underscores
      • may be a valid property shortcut such as this, parent, or view.
    • Scope
      • specifies the category or scope of the target property by including one of the valid scope types:
        • props
        • custom
        • position
        • meta

    Given a full property reference path such as /aContainer/childComponent/button.meta.visible, the Property Identifier is button.meta.visible. Shortcut PropertyReferences are, as noted above, also valid identifiers. See PropertyRef.IDENTIFIER for examples of valid and invalid identifiers.

    Property References have lifecycle - they must be started up and shut down. Starting up a reference will subscribe the given subscriber to the value referred to by the property reference. You must call resolveReference() prior to calling AbstractLifecycle.startup()

    • Method Detail

      • resolveReference

        public void resolveReference()

      • isParsed

        public boolean isParsed()

      • getRefPair

        public java.util.Optional<org.apache.commons.lang3.tuple.Pair<PerspectiveElement,​PropertyKey>> getRefPair()
        If this reference has parsed and resolved correctly, this will return a pair of the element and property that the reference points to. Otherwise, empty.

      • isResolved

        public boolean isResolved()
        Returns:
        true if this is a properly resolved reference to an accessible value

      • getView

        public View getView()

      • getPropertyTree

        @Nullable
public PropertyTree getPropertyTree()
        Returns the property tree where the target property lives

      • getPropertyPath

        public JsonPath getPropertyPath()
        Returns the property path where the target property can be found in its property tree

      • isPropertySelfReference

        public boolean isPropertySelfReference​(PropertyKey targetProperty)
        Returns a boolean that shows if the source and target are referencing the same property

      • getRawPath

        public java.lang.String getRawPath()

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object