Recent changes to Home

WikiPage Home modified by Rob Philipp

Rob Philipp — Wed, 01 Aug 2012 18:09:16 -0000

--- v100
+++ v101
@@ -1,3 +1,5 @@
+Please see \[Project Web\] for current documents.
+
 [Quickstart] | [User Guide] | \[JavaDocs\] 
 
 **Version 0.2.1**

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 20:17:37 -0000

--- v99 
+++ v100 
@@ -394,15 +394,34 @@
 
 The elements of the key are determined by how they appear in the class. For example, notice the "*Division.carNames*" near the bottom of the key-value pair list. The "**Division**" is the class that is being persisted. And "*carNames*" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "*Division.personMap*". As the name suggests, "*personMap*" is a **Map< String, Person >**.
 
-Renderers and Decorators
-
-**Renderer**s are responsible for expressing the objects they render as key-value pairs. And, at the same time, they are responsible for parsing the key-value pairs that adhere to their format, back into an object. For example, in the above text, near the bottom, notice the three key-value pairs that start with "*Division.carNames*". The **CollectionRenderer** knows how to take a collection (List, Set, Queue, etc) and renderer into key-value pairs (and how to parse the key-values back into a collection).
-
-As another example, the keys beginning "*Division.personMap*" found at the bottom of the list of key-value pairs, represent a **Map< String, Person >** and therefore use a **MapRenderer** to create these key-value pairs.
-
-Each **PersistenceRenderer** also provides a method **isRenderer(...)** that returns true if the string passed to it matches the format of something that it renderers.
-
+Renderers
+
+**Renderer**s are responsible for expressing the objects they render as key-value pairs. And, at the same time, they are responsible for parsing the key-value pairs that adhere to their format, back into an object. For example, in the above text, near the bottom, notice the three key-value pairs that start with "*Division.carNames*". The **CollectionRenderer** knows how to take a collection (List, Set, Queue, etc) and renderer into key-value pairs (and how to parse the key-values back into a collection). As another example, the keys beginning "*Division.personMap*" found at the bottom of the list of key-value pairs, represent a **Map< String, Person >** and therefore use a **MapRenderer** to create these key-value pairs.
+
+Each **PersistenceRenderer** also provides a method **isRenderer(...)** that returns true if the key-string passed to it matches the format of something that it renderers. **FreezeDry** provides the following renderers:
+
+Name | Description
+-----|--------------
+PersistenceRenderer | Interface defining what a persistence renderer must have
+AbstractPersistenceRenderer | Manages the *KeyValueBuilder* and the mapping between the types and the *Decorator*s. Also provides some come utilities needed by the renderers.
+LeafNodeRenderer | Renders simple leaf nodes
+MapRenderer | Used to render Maps
+CollectionRenderer | Used for rendering Collections
+FlatteningCollectionRenderer | Renders simple Collections as a single line value, and uses the **CollectionRenderer** to deal with Collections of non-leaf type object (i.e. things that aren't strings or numbers)
+
+Decorators
+
 You may also notice that strings are surrounded by quotes, integers don't have decimals, and that doubles only show 3 decimal places. These decorations and formatting are achieved by **Decorator**s. **Decorator**s also provide an **isDecorated(...)** method that returns true if the string it is passed is decorated (matches its pattern) by that decorator. And if the string is decorated by that decorator, it can "undecorate" it as well.
+
+**FreezeDry** provides the following out of the box:
+
+Name | Description
+-----|------------
+Decorator | Interface defining what a Decorator is.
+StringDecorator | By default surrounds a string with quotes. The opening string and closing string can be specified. For example, an index has an opening string "\[" and a closing string of "\]".
+IntegerDecorator | Formats and parses integers
+DoubleDecorator | Formats and parse floating point numbers. By default has 3 digits to the right of the decimal point. The format can be adjusted.
+BooleanDecorator | Formats parses booleans.
 
 Annotations

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 20:06:10 -0000

--- v98 
+++ v99 
@@ -58,81 +58,81 @@
 The current **FreezeDry** version provides the ability to convert between Java objects and XML, Java objects and JSON, and Java objects and lists of key-value pairs. In its most basic form, converting a Java object into a persisted form is as simple as:
 
     :::java
-    XmlPersistence persistence = new XmlPersistence();
+    final XmlPersistence persistence = new XmlPersistence();
     persistence.write( division, "person.xml" );
 
 And to reconstitute the **division** object from the "person.xml" file, all you need to do is:
 
     :::java
-    XmlPersistence persistence = new XmlPersistence();
+    final XmlPersistence persistence = new XmlPersistence();
     Division redivision = (Division)persistence.read( Division.class, "person.xml" );
 
-The approach used in version 0.1.0 is still available, and in some cases provides a more fine grained control over the transformation of objects and persisted forms into and out of the semantic model using the following approach:
+The approach used in version 0.1.0 is still available. In some cases you might find that the older method, although more complicated, provides more control over the transformation of objects into and persisted forms into and out of the semantic model. The code below demonstrates how to persist a Java object to an XML file by directly using the **PersistenceEngine** and an **XmlWriter**:
 
     :::java
     // create the persistence engine
     final PersistenceEngine engine = new PersistenceEngine();
 
     // create the semantic model that represents the object "division"
     final InfoNode rootNode = engine.createSemanticModel( division );
 	
     // write XML to the file "division.xml"
     try( PrintWriter printWriter = new PrintWriter( new FileWriter( "division.xml" ) ) )
     {
         final XmlWriter writer = new XmlWriter();
         writer.setDisplayTypeInfo( false );
         writer.write( rootNode, printWriter );
     }
     catch( IOException e )
     {
         // deal with any IO exceptions
         ....
     }
 
-Both approaches produces an XML file
+Both approaches produces an XML file like the one below:
 
     :::xml
     
     
         
             
                 Johnny
                     Hernandez
                     13
                     1963-04-22
                     
                         
                             Polly
                             bird
                         
                         ...
                     
                 
                 
                     Julie
                     Prosky
                     15
                 
                 ...
         
     
 
 Don't like the XML output? Well, there are ways to alter the XML file--either through annotations, by implementing a custom node builder, or by implementing a custom reader and writer.
 
 In the next sections we will describe **FreezeDry**'s design.
 
 ---
 
 FreezeDry Landscape
 
 At a high level, **FreezeDry** has is composed of
 
 1. A set of **Persistence** classes responsible for converting between Java objects and their persisted form.
 * A **Persistence Engine** responsible for converting between Java objects and the **Semantic Model**.
 * A **Semantic Model** composed of **InfoNode** objects, each of which hold information about a particular field within the object that is to be persisted or reconstituted.
-* A set of **NodeBuilder** objects that hold detailed information about how to convert a particular Java *Class* between an object and an **InfoNode**.
-* A set of **PersistenceWriter** objects, each of which take a **Semantic Model** and convert it to its persisted form.
-* A set **PersistenceReader** objects, each of which read from the persisted form and convert it to a **Semantic Model**.
+* A set of **NodeBuilder** classes that hold detailed information about how to convert a particular Java *Class* between an object and an **InfoNode**.
+* A set of **PersistenceWriter** classes, each of which take a **Semantic Model** and convert it to its persisted form.
+* A set **PersistenceReader** classes, each of which read from the persisted form and convert it to a **Semantic Model**.
 * And optionally, *annotations* that provide custom instructions to the **PersistenceEngine** for converting between Java objects and the **Semantic Model**.
 
 **FreezeDry** is set up to work right out of the box for most needs. And it mostly does that. In cases where you need to customize its behavior, or where **FreezeDry** gets stuck, it will need your help. It really tries hard to figure out what you're trying to do, but it isn't perfect. It turns out to be easier to convert a Java object into a persisted state, such as an XML or JSON file, than converting a persisted state into a Java object. Largely this is do to the lossy nature of the persistence. For example, in JSON there isn't an elegant way to add type information to the key. And in XML, you could add an attribute *type* to each element. But that isn't usually considered good form. And so in both of these cases, type information is likely lost. And mostly, it is when reconstituting complex objects from persistence where **FreezeDry** may need help.

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 20:01:01 -0000

--- v97 
+++ v98 
@@ -131,8 +131,8 @@
 * A **Persistence Engine** responsible for converting between Java objects and the **Semantic Model**.
 * A **Semantic Model** composed of **InfoNode** objects, each of which hold information about a particular field within the object that is to be persisted or reconstituted.
 * A set of **NodeBuilder** objects that hold detailed information about how to convert a particular Java *Class* between an object and an **InfoNode**.
-* A set of **Writer** objects, each of which take a **Semantic Model** and convert it to its persisted form.
-* A set **Reader** objects, each of which read from the persisted form and convert it to a **Semantic Model**.
+* A set of **PersistenceWriter** objects, each of which take a **Semantic Model** and convert it to its persisted form.
+* A set **PersistenceReader** objects, each of which read from the persisted form and convert it to a **Semantic Model**.
 * And optionally, *annotations* that provide custom instructions to the **PersistenceEngine** for converting between Java objects and the **Semantic Model**.
 
 **FreezeDry** is set up to work right out of the box for most needs. And it mostly does that. In cases where you need to customize its behavior, or where **FreezeDry** gets stuck, it will need your help. It really tries hard to figure out what you're trying to do, but it isn't perfect. It turns out to be easier to convert a Java object into a persisted state, such as an XML or JSON file, than converting a persisted state into a Java object. Largely this is do to the lossy nature of the persistence. For example, in JSON there isn't an elegant way to add type information to the key. And in XML, you could add an attribute *type* to each element. But that isn't usually considered good form. And so in both of these cases, type information is likely lost. And mostly, it is when reconstituting complex objects from persistence where **FreezeDry** may need help.

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:51:43 -0000

--- v96 
+++ v97 
@@ -304,7 +304,7 @@
 
 Readers and Writers
 
-The **Reader** and **Writer** interfaces each define one method.
+The **PersistenceReader** and **PersistenceWriter** interfaces each define one method.
 
     :::java
     public interface PersistenceWriter {

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:51:12 -0000

--- v95 
+++ v96 
@@ -307,20 +307,20 @@
 The **Reader** and **Writer** interfaces each define one method.
 
     :::java
-    public interface Writer {	
-        void write( final InfoNode rootNode, final PrintWriter output );
-    }
-
-The **Writer** accepts the root **InfoNode** of the semantic model and a **PrintWriter** to which to send the persisted form (such as an XML or JSON file).
-
+    public interface PersistenceWriter {	
+        void write( final InfoNode rootNode, final java.io.Writer output );
+    }
+
+The **PersistenceWriter** accepts the root **InfoNode** of the semantic model and a **java.io.Writer** to which to send the persisted form (such as an XML or JSON file).
+
     :::java
-    public interface Reader {
-        InfoNode read( final Class< ? > clazz, final InputStream input );
+    public interface PersistenceReader {
+        InfoNode read( final Class< ? > clazz, final java.io.Reader reader );
     }
     
-The **Reader** accepts an **InputStream** representing the persisted form (such as an XML or JSON file or stream), a class type that represents the class of the object to create from the persisted form, and returns the semantic model as the root **InfoNode** of the tree-like structure. Recall that is exactly the semantic model that the **PersistenceEngine** needs to parse the semantic model into an object.
-
-**FreezeDry** currently provides three **Readers** and three **Writers**.
+The **PersistenceReader** accepts an **java.io.Reader** representing the persisted form (such as an XML or JSON file or stream), a class type that represents the class of the object to create from the persisted form, and returns the semantic model as the root **InfoNode** of the tree-like structure. Recall that is exactly the semantic model that the **PersistenceEngine** needs to parse the semantic model into an object.
+
+**FreezeDry** currently provides three **PersistenceReaders** and three **PersistenceWriters**.
 
 Name | Persisted Form | Description
 -----|----------------|--------------------

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:48:34 -0000

--- v94 
+++ v95 
@@ -392,13 +392,13 @@
 
 Both of these separators can be specified through code.
 
-The elements of the key are determined by how they appear in the class. For example, notice the "Division.carNames" near the bottom of the key-value pair list. The "Division" is the class that is being persisted. And "carNames" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "*Division.personMap*". As the name suggests, "*personMap*" is a **Map< String, Person >**.
-
+The elements of the key are determined by how they appear in the class. For example, notice the "*Division.carNames*" near the bottom of the key-value pair list. The "**Division**" is the class that is being persisted. And "*carNames*" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "*Division.personMap*". As the name suggests, "*personMap*" is a **Map< String, Person >**.
+
 Renderers and Decorators
 
-**Renderer**s are responsible for expressing the objects they render as key-value pairs. And, at the same time, they are responsible for parsing the key-value pairs that adhere to their format, back into an object. For example, in the above text, near the bottom, notice the three key-value pairs that start with "Division.carNames". The **CollectionRenderer** knows how to take a collection (List, Set, Queue, etc) and renderer into key-value pairs (and how to parse the key-values back into a collection).
-
-As another example, the keys beginning "Division.personMap" found at the bottom of the list of key-value pairs, represent a **Map< String, Person >** and therefore use a **MapRenderer** to create these key-value pairs.
+**Renderer**s are responsible for expressing the objects they render as key-value pairs. And, at the same time, they are responsible for parsing the key-value pairs that adhere to their format, back into an object. For example, in the above text, near the bottom, notice the three key-value pairs that start with "*Division.carNames*". The **CollectionRenderer** knows how to take a collection (List, Set, Queue, etc) and renderer into key-value pairs (and how to parse the key-values back into a collection).
+
+As another example, the keys beginning "*Division.personMap*" found at the bottom of the list of key-value pairs, represent a **Map< String, Person >** and therefore use a **MapRenderer** to create these key-value pairs.
 
 Each **PersistenceRenderer** also provides a method **isRenderer(...)** that returns true if the string passed to it matches the format of something that it renderers.

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:47:17 -0000

--- v93 
+++ v94 
@@ -392,7 +392,7 @@
 
 Both of these separators can be specified through code.
 
-The elements of the key are determined by how they appear in the class. For example, notice the "Division.carNames" near the bottom of the key-value pair list. The "Division" is the class that is being persisted. And "carNames" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "Division.personMap". As the name suggests, "personMap" is a **Map< String, Person >**.
+The elements of the key are determined by how they appear in the class. For example, notice the "Division.carNames" near the bottom of the key-value pair list. The "Division" is the class that is being persisted. And "carNames" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "*Division.personMap*". As the name suggests, "*personMap*" is a **Map< String, Person >**.
 
 Renderers and Decorators

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:44:19 -0000

--- v92 
+++ v93 
@@ -392,7 +392,7 @@
 
 Both of these separators can be specified through code.
 
-The elements of the key are determined by how they appear in the class. For example, notice the "Division.carNames" near the bottom of the key-value pair list. The "Division" is the class that is being persisted. And "carNames" is a field in that class, which happens to be a **List< String >**. The "[0]", "[1]", and "[2]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "Division.personMap". As the name suggests, "personMap" is a **Map< String, Person >**.
+The elements of the key are determined by how they appear in the class. For example, notice the "Division.carNames" near the bottom of the key-value pair list. The "Division" is the class that is being persisted. And "carNames" is a field in that class, which happens to be a **List< String >**. The "\[0\]", "\[1\]", and "\[2\]" are the indexes of the element in the list, and are generated by a **PersistenceRenderer** that uses a **Decorator**. Similarly, at the bottom of the list of key-value pairs, you may notice "Division.personMap". As the name suggests, "personMap" is a **Map< String, Person >**.
 
 Renderers and Decorators

WikiPage Home modified by Rob Philipp

Rob Philipp — Fri, 06 Apr 2012 19:43:31 -0000

--- v91 
+++ v92 
@@ -1,4 +1,4 @@
-[Quickstart] | [User Guide] | JavaDocs 
+[Quickstart] | [User Guide] | \[JavaDocs\] 
 
 **Version 0.2.1**