The hierarchy is described in so-called "nodes", where each node may contain an arbitrary number of child nodes but each node can (and will) only have one parent node. The only exemption from this rule is for the topmost (root) node which will have no parent. It is intended that there is only one root node but this depends on the implementation.
It is important that the application invokes closeNode() for each accessed node after it finishes accessing it, i.e. for each previous call to one of the methods create/next/openNode(). If an exception occurs during access the application should not try to read or write further but instead at least re-initialize the storage and restart the access from the beginning.
When writing data to a node the application must always write all data fields in that node. Old data in the node is not preserved between several writes and it is not possible to position the storage on single data fields.
When writing to a node two different kinds of data are distinguished in the API). The first can be seen as "node attributes" and should therefore be used only for values that have a short binary or textual representation (number, short strings, etc.). The other kind is the actual node data. It is accessed with the read/writeData() methods and can in principle be of arbitrary length and type (depending on the implementation, of course). It also depends on the implementation whether attributes and data are treated different or not. For example, an XML storage could use the attributes as tag attributes while putting the data inside the tag.
How the storage behaves under certain conditions like when the root node is closed, openNode is invoked before other nodes are closed, etc. is up to the implementation but in general users of a HierarchicalStorage should assume that reading of a node and/or field is only possible once and that accessing the same storage location again requires a re-initialization (of the node or even the storage) by the application. It should also be assumed that it's only possible to either write to or read from a storage, but not both at the same time.
@author eso | |
| |