GNOME.org
 

[gxml] Improve documentation. Initial performance test for GOM

commit be715a8e7b520862fb2d398ffa877a658607760d
Author: Daniel Espinosa <esodan gmail com>
Date:   Mon Dec 12 13:14:13 2016 -0600

    Improve documentation. Initial performance test for GOM
    
    Improved documentation to easy implement GomElement and
    GomCollection derived classes.

 gxml/GomCollections.vala   |   59 +++++++++++++++
 gxml/GomElement.vala       |   23 ++++++-
 gxml/GomNode.vala          |   23 ++++++
 test/gxml-performance.vala |  176 ++++++++++++++++++++++++++++++++++++++------
 test/tests-config.vala.in  |    4 +-
 5 files changed, 258 insertions(+), 27 deletions(-)
---
diff --git a/gxml/GomCollections.vala b/gxml/GomCollections.vala
index 9935d29..08f7bc8 100644
--- a/gxml/GomCollections.vala
+++ b/gxml/GomCollections.vala
@@ -40,6 +40,8 @@ public interface GXml.GomCollection : Object
   /**
    * Local name of {@link DomElement} objects of {@link element}, which could be
    * contained in this collection.
+   *
+   * Used when reading to add elements to collection.
    */
   public abstract string items_name { get; }
   /**
@@ -92,9 +94,31 @@ public interface GXml.GomCollection : Object
  * child {@link DomElement} of {@link element}, using an index.
  */
 public class GXml.GomArrayList : Object, GomCollection {
+  /**
+   * A collection of node's index refered. Don't modify it manually.
+   */
   protected Queue<int> _nodes_index = new Queue<int> ();
+  /**
+   * Element used to refer of containier element. You should define it at construction time
+   * our set it as a construction property.
+   */
   protected GomElement _element;
+  /**
+   * Local name of {@link DomElement} objects of {@link element}, which could be
+   * contained in this collection.
+   *
+   * Used when reading to add elements to collection. You can set it at construction time,
+   * by, for example, instantaiting a object of the type {@link GomCollection.items_type}
+   * then use {@link GomElement.local_name}'s value.
+   */
   protected string _items_name = "";
+  /**
+   * Objects' type to be referenced by this collection and to deserialize objects.
+   * Derived classes, can initilize this value at constructor or as construct property.
+   *
+   * Used when reading and at initialization time, to know {@link GomElement.local_name}
+   * at runtime.
+   */
   protected GLib.Type _items_type = GLib.Type.INVALID;
   public Queue<int> nodes_index { get { return _nodes_index; } }
   public DomElement element {
@@ -108,11 +132,20 @@ public class GXml.GomArrayList : Object, GomCollection {
       }
     }
   }
+  /**
+   * {@link DomElement.local_name} used to identify nodes at runtime on readding
+   * XML documents. You can set it at construction time see {@link GomCollection.items_name}
+   */
   public string items_name { get { return _items_name; } }
   public Type items_type {
     get { return _items_type; } construct set { _items_type = value; }
   }
 
+  /**
+   * Initialize an {@link GomArrayList} to use an element as child parent
+   * and items of given type. Derived classes are encourage to provide its
+   * own definition, chaining up, to correctly initialize a collection.
+   */
   public GomArrayList.initialize (GomElement element, GLib.Type items_type) {
     _element = element;
     _items_name = "";
@@ -141,6 +174,11 @@ public class GXml.GomArrayList : Object, GomCollection {
                 (_("Invalid atempt to add a node with a different parent document"));
     _nodes_index.push_tail (_element.child_nodes.size - 1);
   }
+  /**
+   * Search for all child nodes in {@link element} of type {@link GomElement}
+   * with a {@link GomElement.local_name} equal to {@link GomCollection.items_name},รง
+   * to add it to collection.
+   */
   public void search () throws GLib.Error {
     for (int i = 0; i < _element.child_nodes.size; i++) {
       var n = _element.child_nodes.get (i);
@@ -160,10 +198,31 @@ public class GXml.GomArrayList : Object, GomCollection {
  * items as key.
  */
 public class GXml.GomHashMap : Object, GomCollection {
+  /**
+   * A collection of node's index refered. Don't modify it manually.
+   */
   protected Queue<int> _nodes_index = new Queue<int> ();
+  /**
+   * A hashtable with all keys as string to node's index refered. Don't modify it manually.
+   */
   protected HashTable<string,int> _hashtable = new HashTable<string,int> (str_hash,str_equal);
+  /**
+   * Element used to refer of containier element. You should define it at construction time
+   * our set it as a construction property.
+   */
   protected GomElement _element;
+  /**
+   * {@link DomElement.local_name} used to identify nodes at runtime on readding
+   * XML documents. You can set it at construction time see {@link GomCollection.items_name}
+   */
   protected string _items_name = "";
+  /**
+   * Objects' type to be referenced by this collection and to deserialize objects.
+   * Derived classes, can initilize this value at constructor or as construct property.
+   *
+   * Used when reading and at initialization time, to know {@link GomElement.local_name}
+   * at runtime.
+   */
   protected GLib.Type _items_type = GLib.Type.INVALID;
   protected string _attribute_key;
   public Queue<int> nodes_index { get { return _nodes_index; } }
diff --git a/gxml/GomElement.vala b/gxml/GomElement.vala
index d81704c..1c7fa9a 100644
--- a/gxml/GomElement.vala
+++ b/gxml/GomElement.vala
@@ -32,6 +32,10 @@ public class GXml.GomElement : GomNode,
                               DomParentNode,
                               DomElement,
                               GomObject {
+  /**
+   * Reference to {@link Attributes} for element's attributes.
+   * Derived classes should avoid to modify it.
+   */
   protected Attributes _attributes;
   // DomNode overrides
   public new string? lookup_prefix (string? nspace) {
@@ -138,11 +142,15 @@ public class GXml.GomElement : GomNode,
     throw new DomError.SYNTAX_ERROR (_("DomElement query_selector_all is not implemented"));
   }
   // GXml.DomElement
+  /**
+   * Use this field to set node's namespace URI. Can used to set it at construction time.
+   */
   protected string _namespace_uri = null;
   public string? namespace_uri { owned get { return _namespace_uri.dup (); } }
   public string? prefix { owned get { return _prefix; } }
   /**
-   * Derived classes should define this value at construction time.
+   * Derived classes should define it at construction time, using
+   * {@link GomNode._local_name} field. This is the node's name.
    */
   public string local_name {
     owned get {
@@ -152,14 +160,23 @@ public class GXml.GomElement : GomNode,
 
   public string tag_name { owned get { return _local_name; } }
 
+  /**
+   * An attribute called 'id'.
+   */
   public string? id {
     owned get { return (this as GomElement).get_attribute ("id"); }
     set { (this as GomObject).set_attribute ("id", value); }
   }
+  /**
+   * An attribute called 'class'.
+   */
   public string? class_name {
     owned get { return (this as GomElement).get_attribute ("class"); }
     set { (this as GomObject).set_attribute ("class", value); }
   }
+  /**
+   * A list of values of all attributes called 'class'.
+   */
   public DomTokenList class_list {
     owned get {
       return new GDomTokenList (this, "class");
@@ -190,6 +207,10 @@ public class GXml.GomElement : GomNode,
    * key if a namespaced attribute.
    */
   public class Attributes : HashMap<string,string>, DomNamedNodeMap  {
+    /**
+     * Holds {@link GomElement} refrence to attributes' parent element.
+     * Derived classes should not modify, but set at construction time.
+     */
     protected GomElement _element;
     public int length { get { return size; } }
     public DomNode? item (int index) { return null; }
diff --git a/gxml/GomNode.vala b/gxml/GomNode.vala
index 8f6547f..34582a4 100644
--- a/gxml/GomNode.vala
+++ b/gxml/GomNode.vala
@@ -27,12 +27,35 @@ public class GXml.GomNode : Object,
                             DomEventTarget,
                             DomNode {
 // DomNode
+  /**
+   * Use this field to set node's local name. Can be set at construction time.
+   */
   protected string _local_name;
+  /**
+   * Use this field to set node's prefix. Can be set at construction time.
+   */
   protected string _prefix;
+  /**
+   * Use this field to set node's base URI. Can be set at construction time.
+   *
+   * See [[https://www.w3.org/TR/dom/#concept-node-base-url]]
+   */
   protected string _base_uri;
+  /**
+   * Use this field to hold node's value. Can be set at construction time.
+   */
   protected string _node_value;
+  /**
+   * Use this field to holding node's parent node. Derived classes should avoid to modify it.
+   */
   protected GXml.DomNode _parent;
+  /**
+   * Use this field to set node's Type. Derived classes should avoid to modify it.
+   */
   protected DomNode.NodeType _node_type;
+  /**
+   * Use this field to set node's child nodes. Derived classes should avoid to modify it.
+   */
   protected GomNodeList _child_nodes;
   public DomNode.NodeType node_type { get { return _node_type; } }
   public string node_name {
diff --git a/test/gxml-performance.vala b/test/gxml-performance.vala
index d0cb94d..83aac3f 100644
--- a/test/gxml-performance.vala
+++ b/test/gxml-performance.vala
@@ -117,6 +117,125 @@ class BookStore : SerializableContainer
   public override string to_string () { return name; }
 }
 
+// GOM Definitions
+class GomName : GomElement
+{
+  construct {
+    _local_name = "Name";
+  }
+  public string get_name () { return this.text_content; }
+  public void   set_name (string name) { this.text_content = name; }
+}
+
+class GomEmail : GomElement
+{
+  construct {
+    _local_name = "Email";
+  }
+  public string get_mail () { return this.text_content; }
+  public void   set_mail (string email) { text_content = email; }
+}
+
+class GomAuthor : GomElement
+{
+  construct {
+    _local_name = "Author";
+  }
+  public Name name { get; set; }
+  public Email email { get; set; }
+  public class Array : GomArrayList {
+    construct {
+      var t = new GomAuthor ();
+      _items_type = typeof (GomAuthor);
+      _items_name = t.local_name;
+    }
+  }
+}
+
+class GomAuthors : GomElement
+{
+  construct {
+    _local_name = "Authors";
+  }
+  public string number { get; set; }
+  public Author.Array array { get; set; default = new Author.Array (); }
+}
+
+class GomInventory : GomElement
+{
+  [Description (nick="##Number")]
+  public int number { get; set; }
+  [Description (nick="##Row")]
+  public int row { get; set; }
+  public string inventory { get; set; }
+  // FIXME: Add DualKeyMap implementation to GOM
+  public class DualKeyMap : GomHashMap {
+    construct {
+      var t = new GomInventory ();
+      _items_type = typeof (GomInventory);
+      _items_name = t.local_name;
+      _attribute_key = "number";
+    }
+  }
+}
+
+class GomCategory : GomElement
+{
+  public string name { get; set; }
+  public class Map : GomHashMap {
+    construct {
+      var t = new GomCategory ();
+      _items_type = typeof (GomCategory);
+      _items_name = t.local_name;
+      _attribute_key = "number";
+    }
+  }
+}
+
+
+class GomResume : GomElement
+{
+  [Description (nick="##Chapter")]
+  public string chapter { get; set; }
+  [Description (nick="##Text")]
+  public string text { get; set; }
+  public class Map : GomHashMap {
+    construct {
+      var t = new GomResume ();
+      _items_type = typeof (GomResume);
+      _items_name = t.local_name;
+      _attribute_key = "chapter";
+    }
+  }
+}
+
+class GomBook : GomElement
+{
+  [Description(nick="##Year")]
+  public string year { get; set; }
+  [Description(isbn="##ISBN")]
+  public string isbn { get; set; }
+  public GomName   name { get; set; }
+  public GomAuthors authors { get; set; }
+  public GomInventory.DualKeyMap inventory_registers { get; set; default = new GomInventory.DualKeyMap (); }
+  public GomCategory.Map categories { get; set; default = new GomCategory.Map (); }
+  public GomResume.Map resumes { get; set; default = new GomResume.Map (); }
+  public class Array : GomArrayList {
+    construct {
+      var t = new GomBook ();
+      _items_type = typeof (GomBook);
+      _items_name = t.local_name;
+    }
+  }
+}
+
+class GomBookStore : GomElement
+{
+  [Description (nick="##name")]
+  public string name { get; set; }
+  public GomBook.Array books { get; set; default = new GomBook.Array (); }
+}
+
 public class Performance
 {
   // ArrayList
@@ -218,22 +337,34 @@ public class Performance
       GLib.message ("Node: "+name+" Val: "+val+ " Children: "+i.to_string ());
 #endif
       if (i > 0)
-        Performance.iterate (n);  
+        Performance.iterate (n);
+    }
+  }
+  public static void iterate_dom (GXml.DomNode node) {
+    foreach (GXml.DomNode n in node.child_nodes) {
+      int i = n.child_nodes.size;
+      string name = n.node_name;
+      string val = n.node_value;
+#if DEBUG
+      GLib.message ("Node: "+name+" Val: "+val+ " Children: "+i.to_string ());
+#endif
+      if (i > 0)
+        Performance.iterate_dom (n);
     }
   }
   public static void add_tests ()
   {
 #if ENABLE_PERFORMANCE_TESTS
-    Test.add_func ("/gxml/performance/read/xdocument", 
+    Test.add_func ("/gxml/performance/read/gomdocument",
     () => {
       try {
         Test.timer_start ();
         double time;
-        var d = new xDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GomDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "Load large document: %g seconds", time);
         Test.timer_start ();
-        iterate (d);
+        iterate_dom (d);
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "Itirate over all loaded nodes: %g seconds", time);
       } catch (GLib.Error e) {
@@ -242,12 +373,12 @@ public class Performance
 #endif
         assert_not_reached ();
       }
-    });Test.add_func ("/gxml/performance/read/gdocument", 
+    });Test.add_func ("/gxml/performance/read/gdocument",
     () => {
       try {
         Test.timer_start ();
         double time;
-        var d = new GDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "Load large document: %g seconds", time);
         Test.timer_start ();
@@ -261,17 +392,16 @@ public class Performance
         assert_not_reached ();
       }
     });
-    Test.add_func ("/gxml/performance/deserialize/xdocument", 
+    Test.add_func ("/gxml/performance/deserialize/gomdocument",
     () => {
       try {
         double time;
         Test.timer_start ();
-        var d = new xDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GomDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "open document from path: %g seconds", time);
         Test.timer_start ();
-        var bs = new BookStore ();
-        bs.deserialize (d);
+        var bs = new GomBookStore (); // FIXME: Requires to read file to document
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "deserialize/performance: %g seconds", time);
       } catch (GLib.Error e) {
@@ -282,22 +412,20 @@ public class Performance
       }
     });
 
-    Test.add_func ("/gxml/performance/serialize/xdocument",
+    Test.add_func ("/gxml/performance/serialize/gomdocument",
     () => {
       try {
         double time;
         Test.timer_start ();
-        var d = new xDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GomDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "open document from path: %g seconds", time);
         Test.timer_start ();
-        var bs = new BookStore ();
-        bs.deserialize (d);
+        var bs = new BookStore (); // FIXME: Requires to read document
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "deserialize/performance: %g seconds", time);
         Test.timer_start ();
-        var d2 = new xDocument ();
-        bs.serialize (d2);
+        // FIXME: Test serialization no sense, there is not this concept on GOM
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "serialize/performance: %g seconds", time);
       } catch (GLib.Error e) {
@@ -307,12 +435,12 @@ public class Performance
         assert_not_reached ();
       }
     });
-    Test.add_func ("/gxml/performance/deserialize/gdocument", 
+    Test.add_func ("/gxml/performance/deserialize/gdocument",
     () => {
       try {
         double time;
         Test.timer_start ();
-        var d = new GDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "open document from path: %g seconds", time);
         Test.timer_start ();
@@ -333,7 +461,7 @@ public class Performance
       try {
         double time;
         Test.timer_start ();
-        var d = new GDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new GDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "GDocument open document from path: %g seconds", time);
         Test.message ("Starting Deserializing...");
@@ -351,7 +479,7 @@ public class Performance
         Test.minimized_result (time, "GDocument serialize/performance: %g seconds", time);
         for (int i = 0; i < 1000000; i++);
         Test.timer_start ();
-        var nf = GLib.File.new_for_path (GXmlTest.get_test_dir () + "/test-large-tw.xml");
+        var nf = GLib.File.new_for_path (GXmlTestConfig.TEST_DIR + "/test-large-tw.xml");
         d2.indent = true;
         d2.save_as (nf);
         time = Test.timer_elapsed ();
@@ -372,7 +500,7 @@ public class Performance
       try {
         double time;
         Test.timer_start ();
-        GLib.File f = GLib.File.new_for_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        GLib.File f = GLib.File.new_for_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         assert (f.query_exists ());
         var d = new GDocument ();
         TDocument.read_doc (d, f, null);
@@ -393,7 +521,7 @@ public class Performance
         Test.minimized_result (time, "GDocument serialize/performance: %g seconds", time);
         for (int i = 0; i < 1000000; i++);
         Test.timer_start ();
-        var nf = GLib.File.new_for_path (GXmlTest.get_test_dir () + "/test-large-tw.xml");
+        var nf = GLib.File.new_for_path (GXmlTestConfig.TEST_DIR + "/test-large-tw.xml");
         d2.indent = true;
         d2.save_as (nf);
         time = Test.timer_elapsed ();
@@ -413,7 +541,7 @@ public class Performance
       try {
         double time;
         Test.timer_start ();
-        var d = new TDocument.from_path (GXmlTest.get_test_dir () + "/test-large.xml");
+        var d = new TDocument.from_path (GXmlTestConfig.TEST_DIR + "/test-large.xml");
         time = Test.timer_elapsed ();
         Test.minimized_result (time, "TDocument open document from path: %g seconds", time);
         Test.message ("Starting Deserializing...");
@@ -431,7 +559,7 @@ public class Performance
         Test.minimized_result (time, "TDocument serialize performance: %g seconds", time);
         for (int i = 0; i < 1000000; i++);
         Test.timer_start ();
-        var nf = GLib.File.new_for_path (GXmlTest.get_test_dir () + "/test-large-tw.xml");
+        var nf = GLib.File.new_for_path (GXmlTestConfig.TEST_DIR + "/test-large-tw.xml");
         d2.indent = true;
         d2.save_as (nf);
         time = Test.timer_elapsed ();
diff --git a/test/tests-config.vala.in b/test/tests-config.vala.in
index 0d87eed..b9f8c37 100644
--- a/test/tests-config.vala.in
+++ b/test/tests-config.vala.in
@@ -1,4 +1,4 @@
 namespace GXmlTestConfig {
-  public static const string TEST_DIR = "@top_srcdir@/test";
-  public static const string TEST_SAVE_DIR = "@top_builddir@/test";
+  public const string TEST_DIR = "@top_srcdir@/test";
+  public const string TEST_SAVE_DIR = "@top_builddir@/test";
 }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]