#############
Property Node
#############

PropertyNode is a `facade`_ that we wrap around the underlying data structures of :doc:`/classes/record-in-flight`, allowing for easier, more intuitive interactions when both reading from and writing to the record.

Typically you won't work with PropertyNode directly, but instead by invoking methods on RecordInFlight that accept :doc:`/extension-concepts/property-path` parameters.

If your extension really needs to get into the guts of a property tree and either manipulate values in place or do some kind of heavy lifting, you can get an instance of PropertyNode to work with like so:

.. code-block:: java

    // RecordInFlight instance methods
    global PropertyNode getOriginalPropertiesRoot();
    global PropertyNode getPropertiesRoot();

.. _facade: https://en.wikipedia.org/wiki/Facade_pattern

Much like :doc:`/classes/json-parse`, PropertyNode treats the underlying data as a tree and wraps each node in its own instance of PropertyNode (thus the class name). You can use property path notation to traverse the tree, retrieving specific nodes of interest. From a given node you can traverse further into that subtree.

*****************
A Common Use Case
*****************

One of the most likely reasons you'll want to work with PropertyNode directly is when you want to manipulate a value at an arbitrary location in a record's property tree, and you don't actually care if value X is three layers down, or two, or has key A or key B.

Maybe the job of your extension in this moment is to capitalize stuff. So you have zero opinion about where to find stuff to capitalize, just that you capitalize whatever you're told to. The user configures the "when" and "where", and you handle the "what".

.. code-block:: java

	// handed a property path value from Valence because of a configuration or mapping etc
	String configuredPropertyPath = 'offices[*].employees[2,5].title';

	PropertyNode root = record.getPropertiesRoot();

	for(PropertyNode node : root.collectAllNodes(configuredPropertyPath)) {
		node.setValue(((String)node.getValue()).capitalize());
	}

	// we capitalized the title on the third and sixth employees, and we did that on every office

This is really powerful because you were able to do your job and remain agnostic about the actual data shape of the record.

**********
Definition
**********

.. code-block:: java

	global Object getValue();

	global void setValue(Object newValue);

	global List<String> getPath(); // concrete property path to this exact node

	global Boolean hasProperty(String concisePropertyPath); // true if a property exists at this path

	global Boolean hasProperty(List<String> normalizedPropertyPath); // true if a property exists at this path

	global Boolean hasProperty(String concisePropertyPath, Boolean notNull); // true if a property exists and its value is not null

	global Boolean hasProperty(List<String> normalizedPropertyPath, Boolean notNull); // true if a property exists and its value is not null

	global Object getPropertyValue(String concisePropertyPath);

	global Object getPropertyValue(List<String> normalizedPropertyPath);

	global List<Object> getPropertyValues(String concisePropertyPath);

	global List<Object> getPropertyValues(List<String> normalizedPropertyPath);

	global void setPropertyValue(String concisePropertyPath, Object value);

	global void setPropertyValue(List<String> normalizedPropertyPath, Object value);

	global void setPropertyValues(String concisePropertyPath, List<Object> values);

	global void setPropertyValues(List<String> normalizedPropertyPath, List<Object> values);

	global List<PropertyNode> collectAllNodes(String concisePropertyPath);

	/**
	 * Recursively gather all nodes in the tree that the passed property path points to. Resolves indefinite
	 * paths into potentially multiple nodes, each of which will be parsed and collected.
	 *
	 * When this method is finished you will receive a final list of all nodes that matched the original path,
	 * and you can go ahead and extract the values to get your real result.
	 *
	 * @param propertyPath A property path using our property path syntax
	 *
	 * @return All nodes at any level at or beneath this one in the tree that match the property path
	 */
	global List<PropertyNode> collectAllNodes(List<String> normalizedPropertyPath);