|
Prepares Adding the property with the specified key.
To be able to deal with the structure supported by hierarchical
configuration implementations the passed in key is of importance,
especially the indices it might contain. The following example should
clearify this: Suppose the actual node structure looks like the
following:
tables
+-- table
+-- name = user
+-- fields
+-- field
+-- name = uid
+-- field
+-- name = firstName
...
+-- table
+-- name = documents
+-- fields
...
In this example a database structure is defined, e.g. all fields of the
first table could be accessed using the key
tables.table(0).fields.field.name. If now properties are
to be added, it must be exactly specified at which position in the
hierarchy the new property is to be inserted. So to add a new field name
to a table it is not enough to say just
config.addProperty("tables.table.fields.field.name", "newField");
The statement given above contains some ambiguity. For instance it is not
clear, to which table the new field should be added. If this method finds
such an ambiguity, it is resolved by following the last valid path. Here
this would be the last table. The same is true for the field;
because there are multiple fields and no explicit index is provided, a
new name property would be added to the last field - which
is propably not what was desired.
To make things clear explicit indices should be provided whenever
possible. In the example above the exact table could be specified by
providing an index for the table element as in
tables.table(1).fields. By specifying an index it can
also be expressed that at a given position in the configuration tree a
new branch should be added. In the example above we did not want to add
an additional name element to the last field of the table,
but we want a complete new field element. This can be
achieved by specifying an invalid index (like -1) after the element where
a new branch should be created. Given this our example would run:
config.addProperty("tables.table(1).fields.field(-1).name", "newField");
With this notation it is possible to add new branches everywhere. We
could for instance create a new table element by
specifying
config.addProperty("tables.table(-1).fields.field.name", "newField2");
(Note that because after the table element a new branch is
created indices in following elements are not relevant; the branch is new
so there cannot be any ambiguities.)
Parameters:
root - the root node of the nodes hierarchy
Parameters:
key - the key of the new property a data object with information needed for the add operation | 