rbrainz 0.1.0 → 0.1.1

data/Rakefile

@@ -1,4 +1,4 @@
-# $Id: Rakefile 4 2007-05-21 02:04:26Z phw $
+# $Id: Rakefile 34 2007-05-29 15:08:03Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -13,7 +13,7 @@ require 'rake/rdoctask'
 # Packaging tasks: -------------------------------------------------------
 
 PKG_NAME = 'rbrainz'
-PKG_VERSION = '0.1.0'
+PKG_VERSION = '0.1.1'
 PKG_FILES = FileList[
   "Rakefile", "LICENSE", "README", "TODO",
   "doc/README.rdoc",

data/TODO

@@ -1,24 +1,29 @@
 =TODO
 
 ==Short term tasks
-* Support relationships (0.1.1)
-* Query collections (0.1.2)
+* Query collections (0.2.0)
 * Support for the score parameter in search result. Could be implemented
   a little bit like in PythonMusicBrainz2, but more flexible. Maybe a result
-  object over which one can iterate to retrieve all results witch the
-  corresponding score. (0.1.2)
+  object over which one can iterate to retrieve all results with the
+  corresponding score. (0.2.0)
    result.each {|entity, score|
      ...
    }
 * Support for the offset parameter for queries on collections
   to retrieve results below the 100 results limit. Could be easily integrated
-  into the result object (see previous point). (0.1.2)
+  into the result object (see previous point). (0.2.0)
 * Make it easier to create MBID objects or allow usage of ID strings
-  where it makes life easier.
+  where it makes life easier (>= 0.2.1).
+* Add usefull constructor parameters to the models (>= 0.2.1).
+* Improve API documentation.
 
 ==Longer term tasks
 * Calculation of disc IDs (0.3.0)
 * User authentication (0.4.0)
 * Querying of user information (0.4.0)
 * PUID submission
-* Full text search (lucene search queries).
+* Full text search (lucene search queries).
+* Implement a command line tool (+mbquery+) for querying the MusicBrainz
+  database which will serve as a usefull example for RBrainz.
+* Support for common extensions (this could be implemented by adding
+  additional extension libraries which extend the existing classes).

data/lib/rbrainz/model/artist.rb

@@ -1,4 +1,4 @@
-# $Id: artist.rb 13 2007-05-22 22:59:57Z phw $
+# $Id: artist.rb 30 2007-05-29 02:12:33Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -18,12 +18,12 @@ module MusicBrainz
       TYPE_PERSON = NS_MMD_1 + 'Person'
       TYPE_GROUP  = NS_MMD_1 + 'Group'
       
-      attr_accessor :name, :sort_name, :disambiguation,
-                    :type, :aliases, :releases
+      attr_accessor :name, :sort_name, :disambiguation, :type
                     
-      attr_reader :begin_date, :end_date
+      attr_reader :begin_date, :end_date, :aliases, :releases
                     
       def initialize
+        super
         @aliases = Array.new
         @releases = Array.new
       end

data/lib/rbrainz/model/entity.rb

@@ -1,20 +1,29 @@
-# $Id: entity.rb 15 2007-05-23 14:31:36Z phw $
+# $Id: entity.rb 30 2007-05-29 02:12:33Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
  
 require 'rbrainz/model/mbid'
+require 'rbrainz/model/relation'
 
 module MusicBrainz
   module Model
 
     # Superclass for all entities.
-    # 
-    # TODO: implement relations.
     class Entity
     
       attr_reader :id
       
+      def initialize
+        @relations = {
+          Relation::TO_ARTIST  => Array.new,
+          Relation::TO_RELEASE => Array.new,
+          Relation::TO_TRACK   => Array.new,
+          Relation::TO_LABEL   => Array.new,
+          Relation::TO_URL     => Array.new,
+        }
+      end
+      
       # Set the MBID.
       # 
       # +mbid+ should be an instance of +MBID+ or a string
@@ -66,6 +75,44 @@ module MusicBrainz
         self.class.entity_type
       end
       
+      # Add a relation to this entity.
+      def add_relation(relation)
+        @relations[relation.target_type] << relation
+      end
+      
+      # Returns the relations of this entity.
+      def get_relations(options = {:target_type => nil, :relation_type => nil,
+                                   :required_attributes => [], :direction => nil})
+        # Select all results depending on the requested target type
+        if options[:target_type]
+          result = @relations[options[:target_type]]
+        else
+          result = []
+          @relations.each_value {|array| result += array}
+        end
+        
+        # Remove relations which don't meet all the criteria.
+        result.delete_if {|relation|
+          (options[:relation_type] and relation.type != options[:relation_type]) \
+          or (options[:required_attributes] and
+              (relation.attributes & options[:required_attributes]).sort \
+               != options[:required_attributes].sort) \
+          or (options[:direction] and relation.direction != options[:direction])
+        }
+        
+        return result
+      end
+      
+      # Return all relation target types for which this entity
+      # has relations defined.
+      def relation_target_types
+        result = []
+        @relations.each_pair {|type, relations|
+          result << type unless relations.empty?
+        }
+        return result
+      end
+      
     end
     
   end

data/lib/rbrainz/model/label.rb

@@ -1,4 +1,4 @@
-# $Id: label.rb 13 2007-05-22 22:59:57Z phw $
+# $Id: label.rb 30 2007-05-29 02:12:33Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -21,11 +21,12 @@ module MusicBrainz
       TYPE_REISSUE_PRODUCTION  = NS_MMD_1 + 'ReissueProduction'
       
       attr_accessor :name, :sort_name, :disambiguation,
-                    :code, :country, :type, :releases
+                    :code, :country, :type
       
-      attr_reader :founding_date, :dissolving_date
+      attr_reader :founding_date, :dissolving_date, :releases
       
       def initialize
+        super
         @releases = Array.new
       end
       

data/lib/rbrainz/model/relation.rb

@@ -0,0 +1,84 @@
+# $Id: relation.rb 33 2007-05-29 14:48:47Z phw $
+# Copyright (c) 2007, Philipp Wolfer
+# All rights reserved.
+# See LICENSE for permissions.
+ 
+module MusicBrainz
+  module Model
+
+    # Relationship class.
+    class Relation
+    
+      DIR_BACKWARD = :backward
+      DIR_FORWARD  = :forward
+      DIR_BOTH     = :both
+      
+      TO_ARTIST  = NS_REL_1 + 'Artist'
+      TO_RELEASE = NS_REL_1 + 'Release'
+      TO_TRACK   = NS_REL_1 + 'Track'
+      TO_LABEL   = NS_REL_1 + 'Label'
+      TO_URL     = NS_REL_1 + 'Url'
+      
+      attr_accessor :type, :direction
+      
+      attr_reader :target, :begin_date, :end_date, :attributes
+      
+      def initialize
+        @attributes = Array.new
+        @target = nil
+      end
+      
+      # Set the target of this relation.
+      # 
+      # The target can either be a object of the type Model::Entity
+      # or a URL.
+      def target=(target)
+        if target.is_a? Entity
+          @target = target
+        else
+          @target = target.to_s
+        end
+      end
+      
+      # Get the target type.
+      def target_type
+        if @target.is_a? Model::Entity
+          case @target.entity_type
+          when :artist
+            return TO_ARTIST
+          when :release
+            return TO_RELEASE
+          when :track
+            return TO_TRACK
+          when :label
+            return TO_LABEL
+          end
+        elsif not @target.nil?
+          return TO_URL
+        end  
+      end
+      
+      # Set the begin date of this relation.
+      # 
+      # Should be an IncompleteDate object or
+      # a date string, which will get converted
+      # into an IncompleteDate.
+      def begin_date=(date)
+        date = IncompleteDate.new date unless date.is_a? IncompleteDate
+        @begin_date = date
+      end
+      
+      # Set the end date of this relation.
+      # 
+      # Should be an IncompleteDate object or
+      # a date string, which will get converted
+      # into an IncompleteDate.
+      def end_date=(date)
+        date = IncompleteDate.new date unless date.is_a? IncompleteDate
+        @end_date = date
+      end
+      
+    end
+    
+  end
+end

data/lib/rbrainz/model/release.rb

@@ -1,4 +1,4 @@
-# $Id: release.rb 15 2007-05-23 14:31:36Z phw $
+# $Id: release.rb 30 2007-05-29 02:12:33Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -32,12 +32,13 @@ module MusicBrainz
       TYPE_SOUNDTRACK     = NS_MMD_1 + 'Soundtrack' 
       TYPE_SPOKENWORD     = NS_MMD_1 + 'Spokenword' 
       
-      attr_accessor :title, :types, :asin, :artist,
+      attr_accessor :title, :asin, :artist,
                     :text_language, :text_script
                     
-      attr_accessor :tracks, :release_events, :discs
+      attr_reader :tracks, :release_events, :discs, :types
       
       def initialize
+        super
         @tracks = Array.new
         @release_events = Array.new
         @discs = Array.new

data/lib/rbrainz/model/track.rb

@@ -1,4 +1,4 @@
-# $Id: track.rb 13 2007-05-22 22:59:57Z phw $
+# $Id: track.rb 30 2007-05-29 02:12:33Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -13,10 +13,12 @@ module MusicBrainz
     # See http://musicbrainz.org/doc/Track.
     class Track < Entity
     
-      attr_accessor :title, :duration, :artist,
-                    :puids, :releases
+      attr_accessor :title, :duration, :artist
+                    
+      attr_reader :puids, :releases
       
       def initialize
+        super
         @puids = Array.new
         @releases = Array.new
       end

data/lib/rbrainz/webservice.rb

@@ -1,6 +1,36 @@
-# $Id: webservice.rb 4 2007-05-21 02:04:26Z phw $
+# $Id: webservice.rb 36 2007-05-29 18:43:36Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
 
+module MusicBrainz
+  module Webservice
+
+    # Connecting to the web service failed.
+    #
+    # This exception is raised if the connection to the server can not be
+    # established due to networking problems (e.g. wrong port number or
+    # server down).
+    class ConnectionError < Exception
+    end
+    
+    # An invalid request was made (invalid IDs or parameters).
+    class RequestError < Exception
+    end
+    
+    # Client requested a resource which requires authentication via HTTP
+    # Digest Authentication.
+    # 
+    # If sent even though user name and password were given: user name and/or
+    # password are incorrect. 
+    class AuthenticationError < Exception
+    end
+    
+    # The requested resource doesn't exist.
+    class ResourceNotFoundError < Exception
+    end
+    
+  end 
+end
+
 require 'rbrainz/webservice/query'

data/lib/rbrainz/webservice/mbxml.rb

@@ -1,4 +1,4 @@
-# $Id: mbxml.rb 17 2007-05-23 16:51:11Z phw $
+# $Id: mbxml.rb 36 2007-05-29 18:43:36Z phw $
 # Copyright (c) 2007, Philipp Wolfer
 # All rights reserved.
 # See LICENSE for permissions.
@@ -14,6 +14,7 @@ module MusicBrainz
     # webservice and create the corresponding model classes.
     # The class understands the MusicBrainz XML Metadata Version 1.0
     # schema.
+    # 
     # See http://musicbrainz.org/doc/MusicBrainzXMLMetaData for more
     # information on the MusicBrainz XML Metadata schema.
     class MBXML
@@ -107,7 +108,7 @@ module MusicBrainz
         return nil
       end
       
-      private
+      private # ----------------------------------------------------------------
       
       # Iterate over a list of artists.
       # 
@@ -119,8 +120,6 @@ module MusicBrainz
       end
       
       # Create an +Artist+ object from the given artist node.
-      # 
-      # TODO: relation list
       def create_artist(node)
         if node.attributes['id'] and @artists[node.attributes['id']]
           artist = @artists[node.attributes['id']]
@@ -131,7 +130,9 @@ module MusicBrainz
         
         # Read all defined data fields
         artist.id = node.attributes['id']
-        artist.type = MBXML.add_metadata_namespace(node.attributes['type']) if node.attributes['type']
+        if node.attributes['type']
+          artist.type = MBXML.add_namespace(node.attributes['type'], Model::NS_MMD_1)
+        end
         
         artist.name = node.elements['name'].text if node.elements['name']
         artist.sort_name = node.elements['sort-name'].text if node.elements['sort-name']
@@ -161,6 +162,15 @@ module MusicBrainz
           }
         end
         
+        # Read the relation list
+        if node.elements['relation-list']
+          node.elements.each('relation-list') {|relation_node|
+            read_relation_list(relation_node) {|relation|
+              artist.add_relation relation
+            }
+          }
+        end
+        
         return artist
       end
       
@@ -176,7 +186,6 @@ module MusicBrainz
       # Create a +Release+ object from the given release node.
       # 
       # TODO: PUID list
-      # TODO: relation list
       def create_release(node)
         if node.attributes['id'] and @releases[node.attributes['id']]
           release = @releases[node.attributes['id']]
@@ -193,7 +202,7 @@ module MusicBrainz
         
         # Read the types
         node.attributes['type'].split(' ').each {|type|
-          release.types << MBXML.add_metadata_namespace(type)
+          release.types << MBXML.add_namespace(type, Model::NS_MMD_1)
         } if node.attributes['type']
         
         # Read the text representation information.
@@ -225,6 +234,15 @@ module MusicBrainz
           }
         end
         
+        # Read the relation list
+        if node.elements['relation-list']
+          node.elements.each('relation-list') {|relation_node|
+            read_relation_list(relation_node) {|relation|
+              release.add_relation relation
+            }
+          }
+        end
+        
         return release
       end
       
@@ -238,8 +256,6 @@ module MusicBrainz
       end
       
       # Create a +Track+ object from the given track node.
-      # 
-      # TODO: relation list
       def create_track(node)
         if node.attributes['id'] and @tracks[node.attributes['id']]
           track = @tracks[node.attributes['id']]
@@ -269,6 +285,15 @@ module MusicBrainz
           }
         end
         
+        # Read the relation list
+        if node.elements['relation-list']
+          node.elements.each('relation-list') {|relation_node|
+            read_relation_list(relation_node) {|relation|
+              track.add_relation relation
+            }
+          }
+        end
+        
         return track
       end
       
@@ -282,8 +307,6 @@ module MusicBrainz
       end
       
       # Create a +Label+ object from the given label node.
-      # 
-      # TODO: Relations
       def create_label(node)
         if node.attributes['id'] and @labels[node.attributes['id']]
           label = @labels[node.attributes['id']]
@@ -294,7 +317,9 @@ module MusicBrainz
         
         # Read all defined data fields
         label.id = node.attributes['id']
-        label.type = MBXML.add_metadata_namespace(node.attributes['type']) if node.attributes['type']
+        if node.attributes['type']
+          label.type = MBXML.add_namespace(node.attributes['type'], Model::NS_MMD_1)
+        end
         
         label.name = node.elements['name'].text if node.elements['name']
         label.sort_name = node.elements['sort-name'].text if node.elements['sort-name']
@@ -318,6 +343,15 @@ module MusicBrainz
           }
         end
       
+        # Read the relation list
+        if node.elements['relation-list']
+          node.elements.each('relation-list') {|relation_node|
+            read_relation_list(relation_node) {|relation|
+              label.add_relation relation
+            }
+          }
+        end
+        
         return label  
       end
       
@@ -385,16 +419,94 @@ module MusicBrainz
         }
       end
       
+      # Iterate over a list of relations.
+      # 
+      # The node must be of the type <em>relation-list</em>.
+      def read_relation_list(node)
+        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
+        
+        # Read all defined data fields
+        if node.attributes['direction']
+          relation.direction = node.attributes['direction'].to_sym
+        end
+        
+        if node.attributes['type']
+          relation.type = MBXML.add_namespace(node.attributes['type'], Model::NS_REL_1)
+        end
+        
+        if node.attributes['begin']
+          relation.begin_date = Model::IncompleteDate.new node.attributes['begin']
+        end
+        
+        if node.attributes['end']
+          relation.begin_end = Model::IncompleteDate.new node.attributes['end']
+        end
+        
+        if node.attributes['attributes']
+          node.attributes['attributes'].split(' ').each {|attribute|
+            relation.attributes << MBXML.add_namespace(attribute, Model::NS_REL_1)
+          }
+        end
+        
+        # Set the target. Either use the target included in the relation
+        # or create a new target according to the target type if no target
+        # is present.
+        case target_type
+        when Model::Relation::TO_ARTIST
+          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'])
+          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'])
+          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'])
+          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'])
+          end
+        when Model::Relation::TO_URL
+          target = node.attributes['target']
+        end
+        
+        relation.target = target
+        
+        return relation
+      end
+      
       # Helper method which will return the given property
-      # extended by the metadata namespace. If the property
+      # extended by the namespace. If the property
       # already includes the namespace it will be returned
       # unchanged.
-      def self.add_metadata_namespace(metadata_property)
-        regex = Regexp.new("/#{Model::NS_MMD_1}[a-z-]/i")
-        unless metadata_property =~ regex
-          return Model::NS_MMD_1 + metadata_property
+      def self.add_namespace(property, namespace)
+        regex = Regexp.new("/#{namespace}[a-z-]/i")
+        unless property =~ regex
+          return namespace + property
         else
-          return metadata_property
+          return property
         end
       end