| Adds the property with the specified key.
To be able to deal with the structure supported by this configuration
implementation the passed in key is of importance, especially the
indices it might contain. The following example should clearify this:
Suppose the actual configuration contains the following elements:
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:
key - the key of the new property
Parameters:
obj - the value of the new property | 