rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/webservice/mbxml.rb

@@ -1,17 +1,19 @@
-# $Id: mbxml.rb 36 2007-05-29 18:43:36Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: mbxml.rb 148 2007-07-19 17:26:33Z phw $
+#
+# Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
+# Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
+# License::   RBrainz is free software distributed under a BSD style license.
+#             See LICENSE[file:../LICENSE.html] for permissions.
 
 require 'rbrainz/model'
+require 'rbrainz/model/scored_collection'
 require 'rexml/document'
-include REXML
 
 module MusicBrainz
   module Webservice
 
     # Class to read the XML data returned by the MusicBrainz
-    # webservice and create the corresponding model classes.
+    # web service and create the corresponding model classes.
     # The class understands the MusicBrainz XML Metadata Version 1.0
     # schema.
     # 
@@ -19,12 +21,31 @@ module MusicBrainz
     # information on the MusicBrainz XML Metadata schema.
     class MBXML
     
-      def initialize(xml)
-        @document = Document.new(xml)
+      # Exception to be raised if a parse error occurs in MBXML.
+      class ParseError < Exception
+      end
+    
+      # Create a new MBXML instance to parse a MusicBrainz metadata document.
+      # 
+      # Parameters:
+      # [stream]  An IO object to read the MusicBrainz metadata XML document from.
+      # [factory] A model factory. An instance of Model::DefaultFactory
+      #           will be used if none is given.
+      #           
+      # Raises:: MBXML::ParseError
+      def initialize(stream, factory=nil)
+        begin
+          @document = REXML::Document.new(stream)
+        rescue REXML::ParseException => e
+          raise ParseError.new(e.to_s)
+        end
+        
+        # Set the model factory
+        factory = Model::DefaultFactory.new unless factory
+        @factory = factory
         
-        # Already loaded artists, releases, tracks
-        # and labels will get cached in these variables
-        # to link to them if they occure multiple times
+        # Already loaded artists, releases, tracks and labels will get cached
+        # in these variables to link to them if they occure multiple times
         # inside the same document.
         @artists  = Hash.new
         @releases = Hash.new
@@ -32,9 +53,9 @@ module MusicBrainz
         @labels   = Hash.new
       end
       
-      # Read the XML string and create an entity model
-      # for the given entity type if it is present in 
-      # the document.
+      # Read the XML string and create an entity model for the given entity
+      # type if it is present in the document.
+      # 
       # Returns nil if no entity of the given type is present.
       def get_entity(entity_type)
         # Search for the first occuring node of type entity which is a child node
@@ -43,80 +64,53 @@ module MusicBrainz
                  [Model::NS_MMD_1, entity_type]]
         
         unless entity.nil? or entity.is_a? REXML::Text
-          case entity.name
-          when 'artist'
-            return create_artist(entity)
-          when 'release'
-            return create_release(entity)
-          when 'track'
-            return create_track(entity)
-          when 'label'
-            return create_label(entity)
-          end
+          create_method = method('create_' + entity.name)
+          create_method.call(entity) if create_method
         else
           return nil
         end
       end
       
-      # Read the XML string and create a list of entity
-      # models for the given entity type. Ther must be
-      # an entity-list element as a child of the metadata
-      # element in the document.
-      # Returns nil if no entity list of the given type is present.
-      # Returns an empty array if the list is empty.
-      def get_entity_list(entity_type)
+      # Read the XML string and create a list of entity models for the given
+      # entity type. There must be an entity-list element as a child of the
+      # +metadata+ element in the document.
+      # 
+      # Returns an empty Collection if the list is empty.
+      # Raises a MBXML::ParseError if no entity-list element can be found.
+      # 
+      # Raises:: MBXML::ParseError
+      def get_entity_list(entity_type, ns=Model::NS_MMD_1)
         # Search for the first occuring node of type entity which is a child node
         # of the metadata element.
-        entity_list = @document.elements["//[local-name()='metadata' and namespace-uri()='%s']/%s-list[1]" %
-                      [Model::NS_MMD_1, entity_type]]
+        entity_list = @document.elements[
+          "//[local-name()='metadata' and namespace-uri()='%s']/[local-name()='%s-list' and namespace-uri()='%s'][1]" %
+            [Model::NS_MMD_1, entity_type, ns]]
         
         unless entity_list.nil? or entity_list.is_a? REXML::Text
-          list = Array.new
+          collection = Model::ScoredCollection.new(entity_list.attributes['count'],
+                                                   entity_list.attributes['offset'])
+          # Select the method to use for reading the list.
+          read_list_method = method('read_' + entity_list.name.gsub('-', '_'))
           
-          case entity_list.name
-          when 'artist-list'
-            read_artist_list(entity_list) {|model|
-              list << model
-            }
-            return list
-          when 'release-list'
-            read_release_list(entity_list) {|model|
-              list << model
-            }
-            return list
-          when 'track-list'
-            read_track_list(entity_list) {|model|
-              list << model
-            }
-            return list
-          when 'label-list'
-            read_label_list(entity_list) {|model|
-              list << model
-            }
-            return list
-          end
+          # Read the entity list and store the entities in the collection.
+          read_list_method.call(entity_list, collection, true) if read_list_method
           
-          if iterator
-            list = Array.new
-            iterator.each {|model|
-              raise model.inspect
-              list << model
-            }
-            return list
-          end
+          return collection
+        else
+          raise ParseError.new("no element %s-list found" % entity_type)
         end
         return nil
       end
       
       private # ----------------------------------------------------------------
       
-      # Iterate over a list of artists.
+      # Iterate over a list of artists and add them to the target collection.
       # 
       # The node must be of the type <em>artist-list</em>.
-      def read_artist_list(node)
-        node.elements.each('artist') {|child|
-          yield create_artist(child)
-        }
+      def read_artist_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'artist', read_scores) do |a|
+          yield a if block_given?
+        end
       end
       
       # Create an +Artist+ object from the given artist node.
@@ -124,7 +118,7 @@ module MusicBrainz
         if node.attributes['id'] and @artists[node.attributes['id']]
           artist = @artists[node.attributes['id']]
         else
-          artist = Model::Artist.new
+          artist = @factory.new_artist
           @artists[node.attributes['id']] = artist
         end
         
@@ -148,19 +142,12 @@ module MusicBrainz
         end
         
         # Read the alias list
-        if node.elements['alias-list']
-          read_alias_list(node.elements['alias-list']) {|artist_alias|
-            artist.aliases << artist_alias
-          }
-        end
+        read_alias_list(node.elements['alias-list'], artist.aliases)
         
         # Read the release list
-        if node.elements['release-list']
-          read_release_list(node.elements['release-list']) {|release|
-            release.artist = artist unless release.artist
-            artist.releases << release
-          }
-        end
+        read_release_list(node.elements['release-list'], artist.releases) {|release|
+          release.artist = artist unless release.artist
+        }
         
         # Read the relation list
         if node.elements['relation-list']
@@ -171,26 +158,29 @@ module MusicBrainz
           }
         end
         
+        # Read the tag list
+        read_tag_list(node.elements['tag-list'], artist.tags)
+        
         return artist
       end
       
-      # Iterate over a list of releases.
+      # Iterate over a list of releases and add them to the target collection.
       # 
       # The node must be of the type <em>release-list</em>.
-      def read_release_list(node)
-        node.elements.each('release') {|child|
-          yield create_release(child)
-        }
+      def read_release_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'release', read_scores) do |a|
+          yield a if block_given?
+        end
       end
       
       # Create a +Release+ object from the given release node.
       # 
-      # TODO: PUID list
+      # TODO:: PUID list
       def create_release(node)
         if node.attributes['id'] and @releases[node.attributes['id']]
           release = @releases[node.attributes['id']]
         else
-          release = Model::Release.new
+          release = @factory.new_release
           @releases[node.attributes['id']] = release
         end
         
@@ -212,28 +202,17 @@ module MusicBrainz
         end
         
         # Read the track list
-        if node.elements['track-list']
-          read_track_list(node.elements['track-list']) {|track|
-            track.artist = release.artist unless track.artist
-            track.releases << release
-            release.tracks << track
-          }
-        end
+        read_track_list(node.elements['track-list'], release.tracks) {|track|
+          track.artist = release.artist unless track.artist
+          track.releases << release
+        }
         
         # Read the release event list
-        if node.elements['release-event-list']
-          read_release_event_list(node.elements['release-event-list']) {|event|
-            release.release_events << event
-          }
-        end
+        read_release_event_list(node.elements['release-event-list'], release.release_events)
         
         # Read the disc list
-        if node.elements['disc-list']
-          read_disc_list(node.elements['disc-list']) {|disc|
-            release.discs << disc
-          }
-        end
-        
+        read_disc_list(node.elements['disc-list'], release.discs)
+                
         # Read the relation list
         if node.elements['relation-list']
           node.elements.each('relation-list') {|relation_node|
@@ -243,16 +222,19 @@ module MusicBrainz
           }
         end
         
+        # Read the tag list
+        read_tag_list(node.elements['tag-list'], release.tags)
+        
         return release
       end
       
-      # Iterate over a list of tracks.
+      # Iterate over a list of tracks and add them to the target collection.
       # 
       # The node must be of the type <em>track-list</em>.
-      def read_track_list(node)
-        node.elements.each('track') {|child|
-          yield create_track(child)
-        }
+      def read_track_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'track', read_scores) do |a|
+          yield a if block_given?
+        end
       end
       
       # Create a +Track+ object from the given track node.
@@ -260,7 +242,7 @@ module MusicBrainz
         if node.attributes['id'] and @tracks[node.attributes['id']]
           track = @tracks[node.attributes['id']]
         else
-          track = Model::Track.new
+          track = @factory.new_track
           @tracks[node.attributes['id']] = track
         end
         
@@ -271,19 +253,12 @@ module MusicBrainz
         track.artist   = create_artist(node.elements['artist']) if node.elements['artist']
         
         # Read the release list
-        if node.elements['release-list']
-          read_release_list(node.elements['release-list']) {|release|
-            release.tracks << track
-            track.releases << release
-          }
-        end
+        read_release_list(node.elements['release-list'], track.releases) {|release|
+          release.tracks << track
+        }
         
         # Read the PUID list
-        if node.elements['puid-list']
-          read_puid_list(node.elements['puid-list']) {|puid|
-            track.puids << puid
-          }
-        end
+        read_puid_list(node.elements['puid-list'], track.puids)
         
         # Read the relation list
         if node.elements['relation-list']
@@ -294,16 +269,19 @@ module MusicBrainz
           }
         end
         
+        # Read the tag list
+        read_tag_list(node.elements['tag-list'], track.tags)
+        
         return track
       end
       
-      # Iterate over a list of labels.
+      # Iterate over a list of labels and add them to the target collection.
       # 
       # The node must be of the type <em>label-list</em>.
-      def read_label_list(node)
-        node.elements.each('label') {|child|
-          yield create_label(child)
-        }
+      def read_label_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'label', read_scores) do |a|
+          yield a if block_given?
+        end
       end
       
       # Create a +Label+ object from the given label node.
@@ -311,7 +289,7 @@ module MusicBrainz
         if node.attributes['id'] and @labels[node.attributes['id']]
           label = @labels[node.attributes['id']]
         else
-          label = Model::Label.new
+          label = @factory.new_label
           @labels[node.attributes['id']] = label
         end
         
@@ -329,19 +307,18 @@ module MusicBrainz
         
         if life_span = node.elements['life-span']
           if life_span.attributes['begin']
-            label.founding_date = Model::IncompleteDate.new life_span.attributes['begin']
+            label.begin_date = Model::IncompleteDate.new life_span.attributes['begin']
           end
           if life_span.attributes['end']
-            label.dissolving_date = Model::IncompleteDate.new life_span.attributes['end']
+            label.end_date = Model::IncompleteDate.new life_span.attributes['end']
           end
         end
         
         # Read the alias list
-        if node.elements['release-list']
-          read_release_list(node.elements['release-list']) {|release|
-            label.releases << release
-          }
-        end
+        read_alias_list(node.elements['alias-list'], label.aliases)
+        
+        # Read the release list
+        read_release_list(node.elements['release-list'], label.releases)
       
         # Read the relation list
         if node.elements['relation-list']
@@ -352,39 +329,61 @@ module MusicBrainz
           }
         end
         
+        # Read the tag list
+        read_tag_list(node.elements['tag-list'], label.tags)
+        
         return label  
       end
       
-      # Iterate over a list of aliases.
+      # Iterate over a list of aliases and add them to the target collection.
       # 
       # The node must be of the type <em>alias-list</em>.
-      def read_alias_list(node)
-        node.elements.each('alias') {|child|
-          yield create_alias(child)
-        }
+      def read_alias_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'alias') do |a|
+          yield a if block_given?
+        end
       end
       
       # Create an +Alias+ object from the given alias node.
       def create_alias(node)
-        alias_model = Model::Alias.new
+        alias_model = @factory.new_alias
         alias_model.name = node.text
-        alias_model.type = node.attributes['type']
+        if node.attributes['type']
+          alias_model.type = MBXML.add_namespace(node.attributes['type'], Model::NS_MMD_1)
+        end
         alias_model.script = node.attributes['script']
         return alias_model
       end
       
-      # Iterate over a list of release events.
+      # Iterate over a list of tags and add them to the target collection.
+      # 
+      # The node must be of the type <em>tag-list</em>.
+      def read_tag_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'tag') do |a|
+          yield a if block_given?
+        end
+      end
+      
+      # Create an +Tag+ object from the given tag node.
+      def create_tag(node)
+        tag = @factory.new_tag
+        tag.text = node.text
+        tag.count = node.attributes['count'].to_i if node.attributes['count']
+        return tag
+      end
+      
+      # Iterate over a list of release events and add them to the target collection.
       # 
       # The node must be of the type <em>release-event-list</em>.
-      def read_release_event_list(node)
-        node.elements.each('event') {|child|
-          yield create_release_event(child)
-        }
+      def read_release_event_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'event') do |a|
+          yield a if block_given?
+        end
       end
       
       # Create an +ReleaseEvent+ object from the given release event node.
-      def create_release_event(node)
-        event = Model::ReleaseEvent.new
+      def create_event(node)
+        event = @factory.new_release_event
         
         # Read all defined data fields
         if node.attributes['date']
@@ -398,40 +397,50 @@ module MusicBrainz
         return event
       end
       
-      # Iterate over a list of PUIDs.
+      # Iterate over a list of PUIDs and add them to the target collection.
       # 
       # The node must be of the type <em>puid-list</em>.
-      def read_puid_list(node)
-        node.elements.each('puid') {|child|
-          yield child.attributes['id']
-        }
+      def read_puid_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'puid') do |a|
+          yield a if block_given?
+        end
       end
       
-      # Iterate over a list of discs.
+      # Create a PUID
+      def create_puid(node)
+        return node.attributes['id']
+      end
+      
+      # Iterate over a list of discs and add them to the target collection.
       # 
       # The node must be of the type <em>disc-list</em>.
-      def read_disc_list(node)
-        node.elements.each('disc') {|child|
-          disc = Model::Disc.new
-          disc.id = child.attributes['id']
-          disc.sectors = child.attributes['sectors'].to_i
-          yield disc
-        }
+      def read_disc_list(list_node, target_collection)
+        read_list(list_node, target_collection, 'disc') do |a|
+          yield a if block_given?
+        end
+      end
+      
+      # Create a +Disc+ object from the given disc node.
+      def create_disc(node)
+        disc = @factory.new_disc
+        disc.id = node.attributes['id']
+        disc.sectors = node.attributes['sectors'].to_i
+        return disc
       end
       
       # Iterate over a list of relations.
       # 
       # The node must be of the type <em>relation-list</em>.
       def read_relation_list(node)
+        target_type = MBXML.add_namespace(node.attributes['target-type'], Model::NS_REL_1)
         node.elements.each('relation') {|child|
-          target_type = MBXML.add_namespace(node.attributes['target-type'], Model::NS_REL_1)
           yield create_relation(child, target_type)
         }
       end
       
       # Create a +Relation+ object from the given relation node.
       def create_relation(node, target_type)
-        relation = Model::Relation.new
+        relation = @factory.new_relation
         
         # Read all defined data fields
         if node.attributes['direction']
@@ -464,29 +473,29 @@ module MusicBrainz
           if node.elements['artist']
             target = create_artist node.elements['artist']
           else
-            target = Model::Artist.new
-            target.id = Model::MBID.from_uuid(:artist, node.attributes['target'])
+            target = @factory.new_artist
+            target.id = Model::MBID.parse(node.attributes['target'], :artist)
           end
         when Model::Relation::TO_RELEASE
           if node.elements['release']
             target = create_release node.elements['release']
           else
-            target = Model::Release.new
-            target.id = Model::MBID.from_uuid(:release, node.attributes['target'])
+            target = @factory.new_release
+            target.id = Model::MBID.parse(node.attributes['target'], :release)
           end
         when Model::Relation::TO_TRACK
           if node.elements['track']
             target = create_track node.elements['track']
           else
-            target = Model::Track.new
-            target.id = Model::MBID.from_uuid(:track, node.attributes['target'])
+            target = @factory.new_track
+            target.id = Model::MBID.parse(node.attributes['target'], :track)
           end
         when Model::Relation::TO_LABEL
           if node.elements['label']
             target = create_label node.elements['label']
           else
-            target = Model::Label.new
-            target.id = Model::MBID.from_uuid(:label, node.attributes['target'])
+            target = @factory.new_label
+            target.id = Model::MBID.parse(node.attributes['target'], :label)
           end
         when Model::Relation::TO_URL
           target = node.attributes['target']
@@ -497,6 +506,45 @@ module MusicBrainz
         return relation
       end
       
+      def read_user_list(list_node, target_collection, read_scores=false)
+        read_list(list_node, target_collection, 'user', read_scores, Model::NS_EXT_1) {|a|
+          yield a if block_given?
+        }
+      end
+
+      def create_user(node)
+        user_model = @factory.new_user
+        # Read the types
+        node.attributes['type'].split(' ').each {|type|
+          user_model.types << MBXML.add_namespace(type, Model::NS_EXT_1)
+        } if node.attributes['type']
+
+        user_model.name = node.elements['name'].text
+        user_model.show_nag = MBXML.get_element(node, 'nag', Model::NS_EXT_1).attributes['show'] == 'true'
+        return user_model
+      end
+      
+      # Helper method that reads a list of a special node type.
+      # There must be a method create_{child_name} which returns an
+      # instance of the corresponding model.
+      def read_list(list_node, target_collection, child_name, read_scores=false, ns=Model::NS_MMD_1)
+        if list_node
+          target_collection.offset = list_node.attributes['offset'].to_i
+          target_collection.count  = list_node.attributes['count'].to_i
+          MBXML.each_element(list_node, child_name, ns) do |child|
+            model = method('create_' + child_name).call(child)
+            if read_scores
+              score = child.attributes['ext:score'].to_i
+              entry = Model::ScoredCollection::Entry.new(model, score)
+            else
+              entry = model
+            end
+            target_collection << entry
+            yield entry if block_given?
+          end
+        end
+      end
+      
       # Helper method which will return the given property
       # extended by the namespace. If the property
       # already includes the namespace it will be returned
@@ -510,6 +558,13 @@ module MusicBrainz
         end
       end
       
+      def self.get_element(node, local_name, ns)
+        node.elements["*[local-name() = '#{local_name}' and namespace-uri() = '#{ns}']"]
+      end
+      
+      def self.each_element(node, local_name, ns, &block)
+        node.elements.each("*[local-name() = '#{local_name}' and namespace-uri()='#{ns}']", &block)
+      end
     end
 
   end