Class ScanEngine

How does it work?

The ScanEngine sits below the XMLEncoder class and is called by it exclusively. The XMLEncoder sends interpretive data by invoking writeExpression(Expression), writeStatement(Statement) and writeObject(Object). The invocations of writeExpression and writeStatement are usually nested into each other and provide more information then necessary to generate the XML representation. Furthermore the meaning of certain Expressions differs depending on the enclosing elements or the inner elements have to be simply discarded.

To cope with this state dependant nature the ScanEngine contains a state machine which is programmed statically (no adjustments are needed, all ScanEngine engines use the same setup). The ScanEngine's job is to decode the Expressions, Statements and certain objects (namely String, null objects and instances which are repeatedly provided to the encoder) into 13 low-level (event) methods, which denote the meaning of the argument. For example an Expression can be an array instantiation which provokes a call to arrayInstantiation or it can be a class resolution leading to a call to ScanEngine. For the state machione the 13 methods are the distinct way to transit from one state to another. Whenever the ScanEngine calls one of the event methods the current's state successor for that event is fetched from the state machine configuration, the successpr becomes the current state and then the event method is called in the new current state. The last step allows the state instance to do something meaningful to the object tree.

The state machine knows the concept of returning to the previous state. This is done using a stack of states which is popped every time a call to writeStatement, writeExpression in the XMLEncoder ends by calling the end() method. Note that due to the inheritance relationship of Encoder and XMLEncoder it is impossible for the ScanEngine itself to decide when an expression or statement ended. This can only be done in case of writeObject(Object) calls because they are not nested.

When the XML persistence mechanism reaches an object twice (and more) it should generate an XML element using the "idref" attribute and add an "id" attribute to its first instantiation. This complicates things a bit because the first instantiation will always be part of the object tree as some Element subclass instance when the second and further objects accesses are written. Therefore the ObjectId class was introduced which is shared between all the object tree elements and has the notion of an "unused" state meaning that no identification is needed. The relationship between an object and its ObjectId instance is stored in the ScanEngine and gets cleared whenever the flush() method is called. This method also writes the currently built object tree and generates the XML representation.