ScanEngine

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> gnu >> java >> beans >> [ encoder overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

Sourc code of gnu.java.beans.encoder.ScanEngine

SOURCE |

Download gnu.java.beans.encoder.ScanEngine

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

gnu.java.beans.encoder
Class ScanEngine

java.lang.Object
  gnu.java.beans.encoder.ScanEngine

public class ScanEngine
extends java.lang.Object

The ScanEngine is the main class of the backend of the XML persistence algorithm. It scans java.beans.Expression and java.beans.Statement instances and some raw objects via the writeObject(java.lang.Object) 55 method and feeds it to a state machine. The state machine then constructs and object tree which is finally written as XML by a Writer implementation.

How does it work?

The ScanEngine sits below the java.beans.XMLEncoder class and is called by it exclusively. The XMLEncoder sends interpretive data by invoking writeExpression(java.beans.Expression) 55 , writeStatement(java.beans.Statement) 55 and writeObject(java.lang.Object) 55 . 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 classResolution(java.lang.String) 55 . 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() 55 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(java.lang.Object) 55 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 gnu.java.beans.encoder.elements.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() 55 method is called. This method also writes the currently built object tree and generates the XML representation.

Field Summary

(package private) ScannerState current
          The currently active scanner state.

(package private) boolean DEBUG
          Change this to true to let the ScanEngine print state transition information.

(package private) java.util.IdentityHashMap objects
          Stores the relationship between objects and their ObjectId instance.

(package private) java.util.Stack parents
          Stores former scanner state and makes it possible to come back to them.

(package private) Root root
          The root of an object tree that is later written to XML.

(package private) java.util.HashMap states
          Stores the scanner engine states as values and their names as keys.

(package private) Writer writer
          The Writer used to generate the XML output.

Constructor Summary

ScanEngine(java.io.OutputStream os)


Method Summary

(package private) void arrayGet(java.lang.String indexAsString)
          Event method that denotes the retrieval of a value in an array.

(package private) void arraySet(java.lang.String indexAsString)
          Event method that denotes the setting of a value in an array.

(package private) void classResolution(java.lang.String className)
          Event method that denotes the resolution of a class.

void close()
          Writes the final bits if the object tree and closes the stream afterwards.

void end()
          Ends the current state and returns to the last one.

void flush()
          Writes the currently constructed object tree out as XML and clears the object to ObjectId relations.

(package private) void listGet()
          Event method that denotes the retrieval of a value in a list.

(package private) void listSet()
          Event method that denotes the setting of a value in a list.

(package private) void methodInvocation(java.lang.String methodName)
          Event method that denotes a (non-static) method invocation.

(package private) void nullObject()
          Event method that denotes the null value.

(package private) void objectArrayInstantiation(java.lang.String arrayClassName, java.lang.String lengthAsString, ObjectId objectId)
          Event method that denotes the instantiation of an object array.

(package private) void objectInstantiation(java.lang.String className, ObjectId objectId)
          Event method that denotes the instantiation of an object.

(package private) void objectReference(ObjectId id)
          Event method that denotes a reference to an existing object.

(package private) void primitiveArrayInstantiation(java.lang.String arrayClassName, java.lang.String lengthAsString, ObjectId objectId)
          Event method that denotes the instantiation of a primitive array.

(package private) void primitiveInstantiation(java.lang.String primitiveName, java.lang.String valueAsString)
          Event method that denotes the instantiation of a primitive.

private ScannerState register(java.lang.String name, ScannerState state)
          Registers a ScannerState under a certain name.

private ObjectId retrieveId(java.lang.Object value)
          Generates or returns an id for the given object which can be activated later if the object is suitable.

void revoke()
          Returns to the last state and deletes the last element in the object tree.

(package private) void staticFieldAccess(java.lang.String className, java.lang.String fieldName)
          Event method that denotes the retrieval of a static field's value.

(package private) void staticMethodInvocation(java.lang.String className, java.lang.String methodName)
          Event method that denotes a static method invocation.

(package private) void stringReference(java.lang.String string)
          Event method that denotes a string.

private void transition(int transition)
          Does a transition from one state to another using the given event.

void writeExpression(java.beans.Expression expr)
          Scans the argument and calls one of event methods.

boolean writeObject(java.lang.Object o)
          Scans the argument and calls one of event methods.

void writeStatement(java.beans.Statement stmt)
          Scans the argument and calls one of event methods.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEBUG

boolean DEBUG

Change this to true to let the ScanEngine print state transition information.

states

java.util.HashMap states

Stores the scanner engine states as values and their names as keys.

parents

java.util.Stack parents

Stores former scanner state and makes it possible to come back to them.

current

ScannerState current

The currently active scanner state.

root

Root root

The root of an object tree that is later written to XML.

writer

Writer writer

The Writer used to generate the XML output.

objects

java.util.IdentityHashMap objects

Stores the relationship between objects and their ObjectId instance.

Constructor Detail

ScanEngine

public ScanEngine(java.io.OutputStream os)

Method Detail

register

private ScannerState register(java.lang.String name,
                              ScannerState state)

Registers a ScannerState under a certain name.

retrieveId

private ObjectId retrieveId(java.lang.Object value)

Generates or returns an id for the given object which can be activated later if the object is suitable.

Objects are unsuitable if they are an instance of a primitive wrapper or String.

writeExpression

public void writeExpression(java.beans.Expression expr)

Scans the argument and calls one of event methods. See the introduction of this class for details.

end

public void end()

Ends the current state and returns to the last one.

revoke

public void revoke()

Returns to the last state and deletes the last element in the object tree.

writeStatement

public void writeStatement(java.beans.Statement stmt)

Scans the argument and calls one of event methods. See the introduction of this class for details.

writeObject

public boolean writeObject(java.lang.Object o)

Scans the argument and calls one of event methods. See the introduction of this class for details.

flush

public void flush()

Writes the currently constructed object tree out as XML and clears the object to ObjectId relations.

close

public void close()

Writes the final bits if the object tree and closes the stream afterwards.

transition

private void transition(int transition)

Does a transition from one state to another using the given event.

This involves saving the current state, retrieving it's successor and setting it as the current state.