== Intro ==
While FlightGear's powerful PropertyTree implementation can be considered to be the core of FlightGear's dynamic, flexible and open nature (and thus also FlightGear's success in the first place) it is more and more often getting obvious that the PropertyTree itself could benefit from an -at least optionally- more structural approach to processing (reading/writing) certain data (property tree variables), whose integrity may be directly critical for the simulator's integrity itself. This applies in particular in an increasingly parallel, multi-threaded environment.
=== Today's Practice ===
Simply put: property tree use in many places in FlightGear today is often following a very simple pattern, where the property tree is simply used as a (very) powerful and easy-to-use "dump space" for all sorts of data and runtime state stored in property tree variables, most of which often being completely typeless or at least very losely-typed, so that access to this state is at most also very losely-organized due to the lack of integrity-enforcing and access-limiting mechanisms.
While this flexibility can be tremendously appreciated from a user's point of view (because it makes it so much more intuitive and easy to use the property tree) this very flexibility (that is, the lack of typing-requirements and data-integrity enforcement mechanisms) can be considered to be a troublesome factor when it comes to ensuring (and optionally also enforcing) proper internal sim state to guarantee valid state for critical variables that may seriously impact simulator performance.
== Problems ==
=== No access control taking place ===
Currently, it is possible -and common practice- for '''all''' properties to be easily accessed (read) and written to from arbitrary FlightGear subsystems and components. In fact, it is even possible for aircraft configuration files and scripts to affect/overwrite crucial internal state.
Encapsulation is basically non-existent for many properties .
=== No concept of (exclusive) property ownership ===
In fact, it is unfortunately even possible to easily register multiple ''writing'' property listeners for the very same property (for example, it would be possible -and has been the case in the past- that registered listeners are exercising write access to properties exclusively owned (at least conceptually) by other components, such as the FDM, whose state would then be automatically invalidated due to its registered listeners each time a property is updated).
So that, one change (write access) to such a property may result in multiple subsequent write accesses '''to the same property''' by its registered listeners.
This is problematic in that property tree state may be mutated and invalidated by its own registered listeners [http://email@example.com/msg02423.html]. And for the majority of FlightGear components relying on tied property listeners, this would indeed result in undefined behavior and can be considered troublesome, because conceptually components such as an FDM engine will normally require exclusive write access to certain output properties.
=== Differentiating between "active" and "passive" listeners ===
* values outside of valid range being written to/read from a node
* "0" values read from nodes that must not be 0
* crucial runtime constants being changed at runtime
== Introducing "Managed Properties" ==
The idea is to introduce so called "managed properties" for crucial runtime state, in order to ensure, enforce and maintain integrity of such state variables by using additional meta information to apply data-integrity requirements, as well as access privileges to prevent important runtime state from being mutated by non- authorized components or invalid data.
== Recommended new 'types'
for nodes ==Currently, there is no clear distinction taking place between arbitrary strings, filenames, paths, property paths or property nodes - this makes it increasingly complicated to keep track of what sort of data is represented by a particular node in the tree and makes it basically impossible to provide validation routines, or even come up with XML schemas that might help validating PropertyList-encoded XML files.
Thus, it is suggested to start differentiating clearly between these different types of strings:
=== File handling related ===
* type="string:path" - value to be specified is a path
* type="string:filename" - value to be specified is a filename
=== Property Tree related ===
* type="string:property-node" - value to be specified is a property node
== Suggested new attributes in PropertyList XML files==
* "live" (or similar) - to indicate dynamically updated (at runtime) node data, i.e. automatically register a corresponding listener for such properties, rather than just using the static value obtained during parse time and treat it as const then, this is likely to be useful for a number of scenarios: right now, each individual FG component requiring this feature, needs to implement it separately, i.e. the autopilot code now features support for dynamically modifiable properties, as well [http://sourceforge.net/mailarchive/message.php?msg_id=47F0027F.6080304%40telus.net], the same applies to the gui/dialog code, which may also make use of "live" properties [http://mail.flightgear.org/pipermail/flightgear-cvslogs/2004-May/007871.html], whose values may change at runtime. Increasingly, it is getting obvious that other FlightGear components may also benefit from such a feature [http://sourceforge.net/mailarchive/forum.php?thread_name=483C054B.5010305%40g2ms.com&forum_name=flightgear-devel]. Thus, it would seem appropriate to generalize the concept of "live properties", whose values may be changed and ought to take effect accordingly. This attribute might from another attribute to indicate the corresponding listener-bound property, i.e.:
<foo type="double" live="true" property="/foo/myfoo/value"/>
* "default-value" - to enable contributors to provide sensible default values in XML files
* "value" attribute - to directly provide node values as attributes more easily in the form of "<node type="string" value="foo"/> instead of the currently required form "<node type="string">foo</node>"
* "description" attribute - to directly document the purpose of a node, so that documentation can be automatically created by walking the property tree
(validation optional: runtime-configurable)
* "unit" to directly keep track of the unit of a numeric value and optionally ensure that only values of same unit are written to variable* "min"/"max" attributes to define valid ranges for numeric values
* "stepping" attribute to define valid stepping for numeric values
* "enum" for textual multi-state variables, to ensure that only valid state can be written to such a variable
* "enum-values" - store valid values for enum type
flip-around/mod" - to specify whether a value overflow means to flip back to the 1st valid state
* "notnil" - value may never be empty/unset
* tie restrictions?
* listener restrictions (max/none)?
* max simultaneously registered active (writing) listeners
=== Permission handling related ===
for constant values that may not change during runtime (or currently: whose changes won't take effect until restart?)
===File handling related === * "filetype:" to explicitly highlight type of file being expected/provided (i.e. "texture/rgb"
* "default-working-dir" - default cwd if only filename specified without path info
Additional Ideas ==
* introducing the concept of "base/frame pointers" for property nodes (and possibly attributes) as described in [http://firstname.lastname@example.org/msg11307.html] would surely simplify PropertyList XML files tremendously and make them much more intuitive to work with (this is in fact conceptually pretty much identical to another suggestion, to provide basically the same facility for (non-relative, file system) paths and filenames provided in aircraft/PropertyList XML files, as posted in response[http://mail.flightgear.org/pipermail/flightgear-devel/2004-November/032299.html] to a request by C. Olson to enable aircraft to become more easily relocatable [http://mail.flightgear.org/pipermail/flightgear-devel/2004-November/032294.html] [http://mail.flightgear.org/pipermail/flightgear-devel/2004-November/032295.html]). This could for example be achieved by generalizing the current concept of aliases or by introducing a possibility to set file-specific (or possibly just global) variables in XML files that can later on be referenced and resolved in attributes or nodes in the XML file, i.e. along the lines of (the details might still need to be discussed, though):
<!-- making use of "base pointers" to directly refer to the proper location instead of using lots of nested relative path specs -->
%FG_ROOT %/myAircraft/myAc-set.xml</aircraft-filename> <some-property type="string"> %ROOT_TREE %/gui/
Implementation-wise, it would be possible to add support for this by either extending the current XMLVisitor code in simgear, or by sub-classing it, so that a static std::map<std::string,std::string> could be used to store variable/value pairs, and automatically parse each encountered attribute or node value for a corresponding variable identifier token that should normally not show up in common use scenarios (such as i.e. '%'). That way, all such occurrences could be automatically looked up in the std::map and resolved to their corresponding equivalents at runtime. So that users would then be able to easily refer "short hands" for well-defined locations (it might make sense to differentiate between local and global xml variables, the latter of which could automatically take effect for all parsed XML files, while the former would only use a lookup map for the root XML file or any files it references using the include directive).