[rygel] media-export: Several more comments



commit 6f634db915fca631ebb952b549aa7c1aad6aee68
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Jan 21 12:51:57 2013 +0100

    media-export: Several more comments

 .../rygel-media-export-media-cache.vala            |   28 ++++++++++++++
 .../rygel-media-export-null-container.vala         |    5 ++-
 .../rygel-media-export-object-factory.vala         |   15 +++++++-
 ...rygel-media-export-query-container-factory.vala |    5 +++
 .../rygel-media-export-root-container.vala         |   39 ++++++++++++++++++--
 .../rygel-media-export-trackable-db-container.vala |    3 ++
 .../rygel-media-export-writable-db-container.vala  |    7 ++++
 7 files changed, 96 insertions(+), 6 deletions(-)
---
diff --git a/src/plugins/media-export/rygel-media-export-media-cache.vala b/src/plugins/media-export/rygel-media-export-media-cache.vala
index fbf2c43..1779386 100644
--- a/src/plugins/media-export/rygel-media-export-media-cache.vala
+++ b/src/plugins/media-export/rygel-media-export-media-cache.vala
@@ -90,6 +90,10 @@ public class Rygel.MediaExport.MediaCache : Object {
         this.remove_by_id (object.id);
     }
 
+    /**
+     * Add the container to the cache, in a database transcation,
+     * rolling back the transaction if necessary.
+     */
     public void save_container (MediaContainer container) throws Error {
         try {
             db.begin ();
@@ -102,6 +106,9 @@ public class Rygel.MediaExport.MediaCache : Object {
         }
     }
 
+    /**
+     * Add the item to the cache.
+     */
     public void save_item (Rygel.MediaItem item) throws Error {
         try {
             db.begin ();
@@ -118,6 +125,12 @@ public class Rygel.MediaExport.MediaCache : Object {
         }
     }
 
+    /**
+     * Create a new container or item instance based on the ID.
+     *
+     * The Rygel server discards the object when the browse request is finished,
+     * after serializing the result.
+     */
     public MediaObject? get_object (string object_id) throws DatabaseError {
         GLib.Value[] values = { object_id };
         MediaObject parent = null;
@@ -427,6 +440,9 @@ public class Rygel.MediaExport.MediaCache : Object {
         return data;
     }
 
+    /**
+     * TODO
+     */
     public Gee.List<string> get_object_attribute_by_search_expression
                                         (string            attribute,
                                          SearchExpression? expression,
@@ -622,6 +638,9 @@ public class Rygel.MediaExport.MediaCache : Object {
         this.db.exec (this.sql.make (SQLString.SAVE_METADATA), values);
     }
 
+    /**
+     * Add the container or item to the cache.
+     */    
     private void create_object (MediaObject object) throws Error {
         int type = ObjectType.CONTAINER;
         GLib.Value parent;
@@ -684,6 +703,15 @@ public class Rygel.MediaExport.MediaCache : Object {
         return false;
    }
 
+    /**
+     * Create a new container or item based on a SQL result.
+     *
+     * The Rygel server discards the object when the browse request is finished,
+     * after serializing the result.
+     *
+     * @param parent The object's parent container.
+     * @param statement a SQLite result indicating the container's details.
+     */
     private MediaObject? get_object_from_statement (MediaContainer? parent,
                                                     Statement       statement) {
         MediaObject object = null;
diff --git a/src/plugins/media-export/rygel-media-export-null-container.vala b/src/plugins/media-export/rygel-media-export-null-container.vala
index 522f9fe..73d2fed 100644
--- a/src/plugins/media-export/rygel-media-export-null-container.vala
+++ b/src/plugins/media-export/rygel-media-export-null-container.vala
@@ -22,8 +22,9 @@ using Rygel;
 using Gee;
 
 /**
- * This is an empty container used to satisfy rygel if no mediadb could be
- * created
+ * This is an empty container used to satisfy Rygel if no mediadb could be
+ * created, or for light-weight hierarchies where the intermediate levels
+ * are not used.
  */
 internal class Rygel.NullContainer : MediaContainer {
     public NullContainer (string          id,
diff --git a/src/plugins/media-export/rygel-media-export-object-factory.vala b/src/plugins/media-export/rygel-media-export-object-factory.vala
index 32a685d..616533f 100644
--- a/src/plugins/media-export/rygel-media-export-object-factory.vala
+++ b/src/plugins/media-export/rygel-media-export-object-factory.vala
@@ -20,9 +20,14 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * A helper class to create container and item
+ * instances based on media-export object IDs,
+ * sometimes delegating to the QueryContainerFactory.
+ */
 internal class Rygel.MediaExport.ObjectFactory : Object {
     /**
-     * Return a new instance of DBContainer
+     * Return a new instance of DBContainer.
      *
      * @param media_db instance of MediaDB
      * @param title title of the container
@@ -54,6 +59,9 @@ internal class Rygel.MediaExport.ObjectFactory : Object {
             return factory.create_from_hashed_id (id, title);
         }
 
+        // Return a suitable container for the top-level virtual folders.
+        // This corresponds to the short-lived NullContainers that 
+        // we used to save these in the database.
         if (id.has_prefix ("virtual-parent:")) {
             return new DBContainer (id, title);
         }
@@ -62,6 +70,11 @@ internal class Rygel.MediaExport.ObjectFactory : Object {
             return new TrackableDbContainer (id, title);
         }
 
+        // Return a writable container for anything with a URI,
+        // such as child folders of the file system,
+        // to allow uploads.
+        // See https://bugzilla.gnome.org/show_bug.cgi?id=676379 to 
+        // give more control over this.
         return new WritableDbContainer (id, title);
     }
 
diff --git a/src/plugins/media-export/rygel-media-export-query-container-factory.vala b/src/plugins/media-export/rygel-media-export-query-container-factory.vala
index 1a91d2c..2ff1f17 100644
--- a/src/plugins/media-export/rygel-media-export-query-container-factory.vala
+++ b/src/plugins/media-export/rygel-media-export-query-container-factory.vala
@@ -20,6 +20,9 @@
 using Gee;
 using GUPnP;
 
+/**
+ * A helper class to create QueryContainer instances based on IDs.
+ */
 internal class Rygel.MediaExport.QueryContainerFactory : Object {
     // private static members
     private static QueryContainerFactory instance;
@@ -124,6 +127,8 @@ internal class Rygel.MediaExport.QueryContainerFactory : Object {
                                                  out upnp_class,
                                                  ref title);
 
+	// Create a node or leaf container,
+        // depending on whether the definition specifies a pattern.
         if (pattern == null || pattern == "") {
             container =  new LeafQueryContainer (expression,
                                                  id,
diff --git a/src/plugins/media-export/rygel-media-export-root-container.vala b/src/plugins/media-export/rygel-media-export-root-container.vala
index e906954..870f6ba 100644
--- a/src/plugins/media-export/rygel-media-export-root-container.vala
+++ b/src/plugins/media-export/rygel-media-export-root-container.vala
@@ -26,12 +26,15 @@ internal struct Rygel.MediaExport.FolderDefinition {
     string definition;
 }
 
-// Titles and definitions of some virtual folders.
+// Titles and definitions of some virtual folders,
+// for use with QueryContainer.
 const Rygel.MediaExport.FolderDefinition[] VIRTUAL_FOLDERS_DEFAULT = {
     { N_("Year"), "dc:date,?" },
     { N_("All"),  "" }
 };
 
+// Titles and definitions of virtual folders for Music,
+// for use with QueryContainer.
 const Rygel.MediaExport.FolderDefinition[] VIRTUAL_FOLDERS_MUSIC = {
     { N_("Artist"), "upnp:artist,?,upnp:album,?" },
     { N_("Album"),  "upnp:album,?" },
@@ -438,7 +441,6 @@ public class Rygel.MediaExport.RootContainer : TrackableDbContainer {
 
     // Signal that the container has been updated with new/changed content.
     private void root_updated () {
-
         // Emit the "container-updated" signal
         this.updated ();
 
@@ -471,6 +473,10 @@ public class Rygel.MediaExport.RootContainer : TrackableDbContainer {
         });
     }
 
+    /** Add the default virtual folders,
+     * for Music, Pictures, etc,
+     * saving them in the cache.
+     */
     private void add_default_virtual_folders () {
         try {
             this.add_virtual_containers_for_class (_("Music"),
@@ -488,12 +494,15 @@ public class Rygel.MediaExport.RootContainer : TrackableDbContainer {
     /**
      * Add a QueryContainer to the provided container,
      * for the specified UpNP class,
-     * with the specified definition.
+     * with the specified definition,
+     * saving it in the cache.
      */
     private void add_folder_definition (MediaContainer   container,
                                         string           item_class,
                                         FolderDefinition definition)
                                         throws Error {
+
+        // Create a container ID that contains the virtual folder definition.
         var id = "%supnp:class,%s,%s".printf (QueryContainer.PREFIX,
                                                item_class,
                                                definition.definition);
@@ -501,11 +510,20 @@ public class Rygel.MediaExport.RootContainer : TrackableDbContainer {
             id = id.slice (0,-1);
         }
 
+        // Create a QueryContainer based on the definition in the ID.
         var factory = QueryContainerFactory.get_default ();
         var query_container = factory.create_from_description_id
                                         (id,
                                          _(definition.title));
 
+        // The QueryContainer's constructor has already run some
+        // SQL to count the number of items.
+        // We remove the container if it has no children.
+        //
+        // Note that all the virtual folders are re-added anyway
+        // when the filesystem changes, so there is no need for
+        // the container to exist in case the query would have
+        // a non-zero result later.
         if (query_container.child_count > 0) {
             query_container.parent = container;
             this.media_db.save_container (query_container);
@@ -514,24 +532,39 @@ public class Rygel.MediaExport.RootContainer : TrackableDbContainer {
         }
     }
 
+    /**
+     * Add a parent container with child containers for the definitions,
+     * saving them in the cache.
+     */
     private void add_virtual_containers_for_class
                                         (string              parent,
                                          string              item_class,
                                          FolderDefinition[]? definitions = null)
                                          throws Error {
+        // Create a container for this virtual folder.
+        // We use a NullContainer just because our MediaCache API takes 
+        // objects and, after saving the details in the database,
+        // it discards the actual container object anyway.
+        // 
+        // This ID prefix is checked later in ObjectFactory.get_container(),
+        // which returns a regular DBContainer instead.
         var container = new NullContainer ("virtual-parent:" + item_class, this, parent);
         this.media_db.save_container (container);
 
+        // Add a child QueryContainer for each of the default definitions.
         foreach (var definition in VIRTUAL_FOLDERS_DEFAULT) {
             this.add_folder_definition (container, item_class, definition);
         }
 
+        // Add a child QueryContainer for each of the additional specified definitions.
         if (definitions != null) {
             foreach (var definition in definitions) {
                 this.add_folder_definition (container, item_class, definition);
             }
         }
 
+        // If no child QueryContainers were added, remove
+        // the provided parent container.
         if (this.media_db.get_child_count (container.id) == 0) {
             this.media_db.remove_by_id (container.id);
         } else {
diff --git a/src/plugins/media-export/rygel-media-export-trackable-db-container.vala b/src/plugins/media-export/rygel-media-export-trackable-db-container.vala
index 38030bd..af41c00 100644
--- a/src/plugins/media-export/rygel-media-export-trackable-db-container.vala
+++ b/src/plugins/media-export/rygel-media-export-trackable-db-container.vala
@@ -21,6 +21,9 @@
  */
 using Gee;
 
+/**
+ * A DB container that is trackable.
+ */
 public class Rygel.MediaExport.TrackableDbContainer : TrackableContainer,
                                                       DBContainer {
     public TrackableDbContainer (string id, string title) {
diff --git a/src/plugins/media-export/rygel-media-export-writable-db-container.vala b/src/plugins/media-export/rygel-media-export-writable-db-container.vala
index de7a310..789d65d 100644
--- a/src/plugins/media-export/rygel-media-export-writable-db-container.vala
+++ b/src/plugins/media-export/rygel-media-export-writable-db-container.vala
@@ -21,6 +21,13 @@
  */
 using Gee;
 
+/**
+ * A DB container that is both Trackable and Writable.
+ *
+ * Clients can upload items to this container, causing
+ * the items to be saved to the filesystem to be
+ * served again subsequently.
+ */
 internal class Rygel.MediaExport.WritableDbContainer : TrackableDbContainer,
                                                        Rygel.WritableContainer {
     public ArrayList<string> create_classes { get; set; }



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]