simple.xml.graph
Class CycleStrategy

java.lang.Object
  extended by simple.xml.graph.CycleStrategy
All Implemented Interfaces:
Strategy

public class CycleStrategy
extends java.lang.Object
implements Strategy

The CycleStrategy represents a strategy that is used to augment the deserialization and serialization process such that cycles in an object graph can be supported. This adds additional attributes to the serializaed XML elements so that during the deserialization process an objects cycles can be created. Without the use of a strategy such as this, cycles could cause an infinite loop during the serialization process while traversing the graph.

 
    <root id="1">
       <object id="2">
          <object id="3" name="name">Example</item>
          <object reference="2"/>
       </object>
    </root>
 
 
In the above serialized XML there is a circular reference, where the XML element with id "2" contains a reference to itself. In most data binding frameworks this will cause an infinite loop, or in some cases will just fail to represent the references well. With this strategy you can ensure that cycles in complex object graphs will be maintained and can be serialized safely.

Author:
Niall Gallagher
See Also:
Persister, Strategy

Constructor Summary
CycleStrategy()
          Constructor for the CycleStrategy object.
CycleStrategy(java.lang.String mark, java.lang.String refer)
          Constructor for the CycleStrategy object.
CycleStrategy(java.lang.String mark, java.lang.String refer, java.lang.String label)
          Constructor for the CycleStrategy object.
CycleStrategy(java.lang.String mark, java.lang.String refer, java.lang.String label, java.lang.String length)
          Constructor for the CycleStrategy object.
 
Method Summary
 Type getElement(java.lang.Class field, NodeMap node, java.util.Map map)
          This method is used to read an object from the specified node.
 Type getRoot(java.lang.Class field, NodeMap node, java.util.Map map)
          This method is used to read an object from the specified node.
 boolean setElement(java.lang.Class field, java.lang.Object value, NodeMap node, java.util.Map map)
          This is used to set the reference in to the XML element that is to be written.
 boolean setRoot(java.lang.Class field, java.lang.Object value, NodeMap node, java.util.Map map)
          This is used to set the reference in to the XML element that is to be written.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CycleStrategy

public CycleStrategy()
Constructor for the CycleStrategy object. This is used to create a strategy with default values. By default the values used are "id" and "reference". These values will be added to XML elements during the serialization process. And will be used to deserialize the object cycles fully.


CycleStrategy

public CycleStrategy(java.lang.String mark,
                     java.lang.String refer)
Constructor for the CycleStrategy object. This is used to create a strategy with the sepcified attributes, which will be added to serialized XML elements. These attributes are used to serialize the objects in such a way the cycles in the object graph can be deserialized and used fully.

Parameters:
mark - this is used to mark the identity of an object
refer - this is used to refer to an existing object

CycleStrategy

public CycleStrategy(java.lang.String mark,
                     java.lang.String refer,
                     java.lang.String label)
Constructor for the CycleStrategy object. This is used to create a strategy with the sepcified attributes, which will be added to serialized XML elements. These attributes are used to serialize the objects in such a way the cycles in the object graph can be deserialized and used fully.

Parameters:
mark - this is used to mark the identity of an object
refer - this is used to refer to an existing object
label - this is used to specify the class for the field

CycleStrategy

public CycleStrategy(java.lang.String mark,
                     java.lang.String refer,
                     java.lang.String label,
                     java.lang.String length)
Constructor for the CycleStrategy object. This is used to create a strategy with the sepcified attributes, which will be added to serialized XML elements. These attributes are used to serialize the objects in such a way the cycles in the object graph can be deserialized and used fully.

Parameters:
mark - this is used to mark the identity of an object
refer - this is used to refer to an existing object
label - this is used to specify the class for the field
length - this is the length attribute used for arrays
Method Detail

getRoot

public Type getRoot(java.lang.Class field,
                    NodeMap node,
                    java.util.Map map)
             throws java.lang.Exception
This method is used to read an object from the specified node. In order to get the root type the field and node map are specified. The field represents the annotated method or field within the deserialized object. The node map is used to get the attributes used to describe the objects identity, or in the case of an existing object it contains an object reference.

Specified by:
getRoot in interface Strategy
Parameters:
field - the method or field in the deserialized object
node - this is the XML element attributes to read
map - this is the session map used for deserialization
Returns:
this returns an instance to insert into the object
Throws:
java.lang.Exception - thrown if the class cannot be resolved

getElement

public Type getElement(java.lang.Class field,
                       NodeMap node,
                       java.util.Map map)
                throws java.lang.Exception
This method is used to read an object from the specified node. In order to get the root type the field and node map are specified. The field represents the annotated method or field within the deserialized object. The node map is used to get the attributes used to describe the objects identity, or in the case of an existing object it contains an object reference.

Specified by:
getElement in interface Strategy
Parameters:
field - the method or field in the deserialized object
node - this is the XML element attributes to read
map - this is the session map used for deserialization
Returns:
this returns an instance to insert into the object
Throws:
java.lang.Exception - thrown if the class cannot be resolved

setRoot

public boolean setRoot(java.lang.Class field,
                       java.lang.Object value,
                       NodeMap node,
                       java.util.Map map)
This is used to set the reference in to the XML element that is to be written. This will either insert an object identity if the object has not previously been written, or, if the object has already been written in a previous element, this will write the reference to that object. This allows all cycles within the graph to be serialized so that they can be fully deserialized.

Specified by:
setRoot in interface Strategy
Parameters:
field - the type of the field or method in the object
value - this is the actual object that is to be written
node - tihs is the XML element attribute map to use
map - this is the session map used for the serialization
Returns:
returns true if the object has been fully serialized

setElement

public boolean setElement(java.lang.Class field,
                          java.lang.Object value,
                          NodeMap node,
                          java.util.Map map)
This is used to set the reference in to the XML element that is to be written. This will either insert an object identity if the object has not previously been written, or, if the object has already been written in a previous element, this will write the reference to that object. This allows all cycles within the graph to be serialized so that they can be fully deserialized.

Specified by:
setElement in interface Strategy
Parameters:
field - the type of the field or method in the object
value - this is the actual object that is to be written
node - tihs is the XML element attribute map to use
map - this is the session map used for the serialization
Returns:
returns true if the object has been fully serialized