Package com.inductiveautomation.perspective.gateway.property

Class PropertyReference

java.lang.Object

com.inductiveautomation.ignition.common.lifecycle.AbstractLifecycle

com.inductiveautomation.perspective.gateway.property.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()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	PropertyReference.PropertyReferenceParseException

Constructor Summary

Constructors

Constructor	Description
PropertyReference(PerspectiveElement target, String referencePath, Consumer<PropertyTreeChangeEvent> subscriber, Set<Origin> acceptableOrigins)

Method Summary

Modifier and Type	Method	Description
JsonPath	getPropertyPath()	Returns the property path where the target property can be found in its property tree
PropertyTree	getPropertyTree()	Returns the property tree where the target property lives
String	getRawPath()
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.
View	getView()
boolean	isParsed()
boolean	isPropertySelfReference(PropertyKey targetProperty)	Returns a boolean that shows if the source and target are referencing the same property
boolean	isResolved()
protected void	onShutdown()
protected void	onStartup()
Optional<QualifiedValue>	read()
Optional<QualifiedValue>	read(JsonPath path)
void	resolveReference()
String	toString()

Methods inherited from class com.inductiveautomation.ignition.common.lifecycle.AbstractLifecycle

isRunning, shutdown, startup

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

PropertyReference

public PropertyReference(PerspectiveElement target,
 String referencePath,
 Consumer<PropertyTreeChangeEvent> subscriber,
 Set<Origin> acceptableOrigins)

Method Details

resolveReference

public void resolveReference()

isParsed

public boolean isParsed()

getRefPair

public 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 String getRawPath()

read

public Optional<QualifiedValue> read()

read

public Optional<QualifiedValue> read(JsonPath path)

onStartup

protected void onStartup()

Specified by:

onStartup in class AbstractLifecycle

onShutdown

protected void onShutdown()

Specified by:

onShutdown in class AbstractLifecycle

toString

public String toString()

Overrides:

toString in class Object