rbrainz 0.1.1 → 0.2.0

data/lib/rbrainz/webservice.rb

@@ -1,9 +1,24 @@
-# $Id: webservice.rb 36 2007-05-29 18:43:36Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: webservice.rb 146 2007-07-19 16:33:38Z 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.
 
-module MusicBrainz
+module MusicBrainz # :nodoc:
+
+  # Classes for interacting with the MusicBrainz XML web service.
+  # 
+  # The WebService class talks to a server implementing the MusicBrainz XML
+  # web service. It mainly handles URL generation and network I/O. Use this
+  # if maximum control is needed.
+  # 
+  # The Query class provides a convenient interface to the most commonly used
+  # features of the web service. By default it uses Webservice to retrieve data
+  # and the MBXML parser to parse the responses. The results are object trees
+  # using the MusicBrainz domain model.
+  # 
+  # See:: Model
   module Webservice
 
     # Connecting to the web service failed.
@@ -14,7 +29,10 @@ module MusicBrainz
     class ConnectionError < Exception
     end
     
-    # An invalid request was made (invalid IDs or parameters).
+    # An invalid request was made.
+    # 
+    # This exception is raised if the client made an invalid request. That could
+    # be syntactically invalid identifiers or unknown or invalid parameter values.
     class RequestError < Exception
     end
     
@@ -29,6 +47,14 @@ module MusicBrainz
     # The requested resource doesn't exist.
     class ResourceNotFoundError < Exception
     end
+
+    # The returned resource was invalid.
+    # 
+    # This may be due to a malformed XML document or if the requested data
+    # wasn't part of the response. It can only occur in case of bugs in the web
+    # service itself.
+    class ResponseError < Exception
+    end
     
   end 
 end

data/lib/rbrainz/webservice/filter.rb

@@ -1,7 +1,9 @@
-# $Id: filter.rb 4 2007-05-21 02:04:26Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: filter.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 'uri'
 
@@ -9,17 +11,33 @@ module MusicBrainz
   module Webservice
 
     # Base class for all filter classes.
+    # 
+    # Filter classes are initialized with a set of criteria and are then
+    # applied to collections of items. The criteria are usually strings
+    # or integer values, depending on the filter.
     class AbstractFilter
       
-      # The parameter +filter+ is a hash with filter options.
-      # The the concrete classes for a description of those
+      # The parameter _filter_ is a hash with filter options.
+      # See the concrete classes for a description of those
       # options.
+      # 
+      # The following options are available for all filters:
+      # [:limit]  The maximum number of entries returned. Defaults
+      #           to 25, the maximum allowed value is 100.
+      # [:offset] Return search results starting at a given offset. Used
+      #           for paging through more than one page of results.
+      # [:query]  A Lucene search query. The query parameter is a search
+      #           string which will be passed to the underlying Lucene search
+      #           engine. It must follow the syntax described in
+      #           http://musicbrainz.org/doc/TextSearchSyntax.
       def initialize(filter)
-        raise 'Tried to initialize abstract class.'
+        @filter = Hash.new
+        @filter[:limit]  = filter[:limit]  if filter[:limit]
+        @filter[:offset] = filter[:offset] if filter[:offset]
+        @filter[:query]  = filter[:query]  if filter[:query]
       end
       
-      # Returns the filter list as a query string
-      # (without leading +&+).
+      # Returns the filter list as a query string (without leading <em>&</em>).
       def to_s
         @filter.to_a.map {|name, value|
           '%s=%s' % [URI.escape(name.to_s), URI.escape(value.to_s)]
@@ -28,23 +46,37 @@ module MusicBrainz
       
     end
     
+    # A filter for the artist collection.
     class ArtistFilter < AbstractFilter
     
-      # The parameter +filter+ is a hash with filter options:
-      # [:name]  Fetch a list of artists with a matching name.
-      # [:limit] The maximum number of artists returned. Defaults
-      #          to 25, the maximum allowed value is 100. 
+      # The parameter _filter_ is a hash with filter options. At least the
+      # <tt>:name</tt> filter must be specified.
+      # 
+      # Available filter options:
+      # [:name]   Fetch a list of artists with a matching name.
+      # [:limit]  The maximum number of artists returned. Defaults
+      #           to 25, the maximum allowed value is 100.
+      # [:offset] Return search results starting at a given offset. Used
+      #           for paging through more than one page of results.
+      # [:query]  A Lucene search query. The query parameter is a search
+      #           string which will be passed to the underlying Lucene search
+      #           engine. It must follow the syntax described in
+      #           http://musicbrainz.org/doc/TextSearchSyntax.
       def initialize(filter)
-        @filter = Hash.new
-        @filter[:name]  = filter[:name]  if filter[:name]
-        @filter[:limit] = filter[:limit] if filter[:limit]
+        Utils.check_options filter, :name, :limit, :offset, :query
+        super(filter)
+        @filter[:name] = filter[:name]  if filter[:name]
       end
     
     end
     
+    # A filter for the release collection.
     class ReleaseFilter < AbstractFilter
     
-      # The parameter +filter+ is a hash with filter options:
+      # The parameter _filter_ is a hash with filter options. At least one
+      # filter despite <tt>:limit</tt> and <tt>:offset</tt> must be specified.
+      # 
+      # Available filter options:
       # [:title]     Fetch a list of releases with a matching title.
       # [:discid]    Fetch all releases matching to the given DiscID.
       # [:artist]    The returned releases should match the given artist name.
@@ -61,26 +93,38 @@ module MusicBrainz
       # [:script]    The script used in this release.
       # [:limit]     The maximum number of tracks returned. Defaults
       #              to 25, the maximum allowed value is 100. 
+      # [:offset]    Return search results starting at a given offset. Used
+      #              for paging through more than one page of results.
+      # [:query]     A Lucene search query. The query parameter is a search
+      #              string which will be passed to the underlying Lucene search
+      #              engine. It must follow the syntax described in
+      #              http://musicbrainz.org/doc/TextSearchSyntax.
       def initialize(filter)
-        @filter = Hash.new
-        @filter[:title]     = filter[:title]     if filter[:title]
-        @filter[:discid]    = filter[:discid]    if filter[:discid]
-        @filter[:artist]    = filter[:artist]    if filter[:artist]
-        @filter[:artistid]  = filter[:artistid]  if filter[:artistid]
+        Utils.check_options filter, 
+          :limit, :offset, :query, :title, :discid, :artist, :artistid, 
+          :releasetypes, :count, :date, :asin, :lang, :script
+        super(filter)
+        @filter[:title]        = filter[:title]     if filter[:title]
+        @filter[:discid]       = filter[:discid]    if filter[:discid]
+        @filter[:artist]       = filter[:artist]    if filter[:artist]
+        @filter[:artistid]     = filter[:artistid]  if filter[:artistid]
         @filter[:releasetypes] = filter[:releasetypes] if filter[:releasetypes]
-        @filter[:count]     = filter[:count]     if filter[:count]
-        @filter[:date]      = filter[:date]      if filter[:date]
-        @filter[:asin]      = filter[:asin]      if filter[:asin]
-        @filter[:lang]      = filter[:lang]      if filter[:lang]
-        @filter[:script]    = filter[:script]    if filter[:script]
-        @filter[:limit]     = filter[:limit]     if filter[:limit]
+        @filter[:count]        = filter[:count]     if filter[:count]
+        @filter[:date]         = filter[:date]      if filter[:date]
+        @filter[:asin]         = filter[:asin]      if filter[:asin]
+        @filter[:lang]         = filter[:lang]      if filter[:lang]
+        @filter[:script]       = filter[:script]    if filter[:script]
       end
     
     end
     
+    # A filter for the track collection.
     class TrackFilter < AbstractFilter
     
-      # The parameter +filter+ is a hash with filter options:
+      # The parameter _filter_ is a hash with filter options. At least the
+      # <tt>:title</tt> filter must be specified.
+      # 
+      # Available filter options:
       # [:title]     Fetch a list of tracks with a matching title.
       # [:artist]    The returned tracks have to match the given
       #              artist name.
@@ -97,36 +141,69 @@ module MusicBrainz
       # [:releasetype] The type of the release this track appears on
       # [:limit]     The maximum number of tracks returned. Defaults
       #              to 25, the maximum allowed value is 100. 
+      # [:offset]    Return search results starting at a given offset. Used
+      #              for paging through more than one page of results.
+      # [:query]     A Lucene search query. The query parameter is a search
+      #              string which will be passed to the underlying Lucene search
+      #              engine. It must follow the syntax described in
+      #              http://musicbrainz.org/doc/TextSearchSyntax.
       def initialize(filter)
-        @filter = Hash.new
-        @filter[:title]     = filter[:title]     if filter[:title]
-        @filter[:artist]    = filter[:artist]    if filter[:artist]
-        @filter[:release]   = filter[:release]   if filter[:release]
-        @filter[:duration]  = filter[:duration]  if filter[:duration]
-        @filter[:tracknum]  = filter[:tracknum]  if filter[:tracknum]
-        @filter[:artistid]  = filter[:artistid]  if filter[:artistid]
-        @filter[:releaseid] = filter[:releaseid] if filter[:releaseid]
-        @filter[:puid]      = filter[:puid]      if filter[:puid]
-        @filter[:count]     = filter[:count]     if filter[:count]
+        Utils.check_options filter, 
+            :limit, :offset, :query, :title, :artist, :release, :duration, 
+            :tracknum, :artistid, :releaseid, :puid, :count, :releasetype
+        super(filter)
+        @filter[:title]       = filter[:title]     if filter[:title]
+        @filter[:artist]      = filter[:artist]    if filter[:artist]
+        @filter[:release]     = filter[:release]   if filter[:release]
+        @filter[:duration]    = filter[:duration]  if filter[:duration]
+        @filter[:tracknum]    = filter[:tracknum]  if filter[:tracknum]
+        @filter[:artistid]    = filter[:artistid]  if filter[:artistid]
+        @filter[:releaseid]   = filter[:releaseid] if filter[:releaseid]
+        @filter[:puid]        = filter[:puid]      if filter[:puid]
+        @filter[:count]       = filter[:count]     if filter[:count]
         @filter[:releasetype] = filter[:releasetype] if filter[:releasetype]
-        @filter[:limit]     = filter[:limit]     if filter[:limit]
       end
     
     end
     
+    # A filter for the label collection.
     class LabelFilter < AbstractFilter
     
-      # The parameter +filter+ is a hash with filter options:
-      # [:name]  Fetch a list of labels with a matching name.
-      # [:limit] The maximum number of labels returned. Defaults
-      #          to 25, the maximum allowed value is 100. 
+      # The parameter _filter_ is a hash with filter options. At least the
+      # <tt>:name</tt> filter must be specified.
+      # 
+      # Available filter options:
+      # [:name]   Fetch a list of labels with a matching name.
+      # [:limit]  The maximum number of labels returned. Defaults
+      #           to 25, the maximum allowed value is 100. 
+      # [:offset] Return search results starting at a given offset. Used
+      #           for paging through more than one page of results.
+      # [:query]  A Lucene search query. The query parameter is a search
+      #           string which will be passed to the underlying Lucene search
+      #           engine. It must follow the syntax described in
+      #           http://musicbrainz.org/doc/TextSearchSyntax.
       def initialize(filter)
-        @filter = Hash.new
-        @filter[:name]  = filter[:name]  if filter[:name]
-        @filter[:limit] = filter[:limit] if filter[:limit]
+        Utils.check_options filter, :limit, :offset, :query, :name
+        super(filter)
+        @filter[:name] = filter[:name]  if filter[:name]
       end
     
     end
     
+    # A filter to query a user by his username.
+    class UserFilter
+      def initialize(name=nil)
+        @filter = Hash.new
+        @filter[:name] = name if name
+      end
+      
+      # Returns the filter list as a query string (without leading <em>&</em>).
+      def to_s
+        @filter.to_a.map {|name, value|
+          '%s=%s' % [URI.escape(name.to_s), URI.escape(value.to_s)]
+        }.join('&')
+      end
+    end
+    
   end
 end

data/lib/rbrainz/webservice/includes.rb

@@ -1,7 +1,9 @@
-# $Id: includes.rb 4 2007-05-21 02:04:26Z phw $
-# Copyright (c) 2007, Philipp Wolfer
-# All rights reserved.
-# See LICENSE for permissions.
+# $Id: includes.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 'uri'
 
@@ -9,12 +11,17 @@ module MusicBrainz
   module Webservice
 
     # Base class for all include classes.
+    # 
+    # Includes are used to specify which detail information should be returned
+    # for an entity search. There is one include class for each entity type.
     class AbstractIncludes
     
       def initialize(includes)
         raise 'Tried to initialize abstract class.'
       end 
       
+      # Returns the includes as a parameter that can be used in a MusicBrainz
+      # XML web service URI.
       def to_s
         if @parameters.size > 0
           return 'inc=' + URI.escape(@parameters.join(' '))
@@ -22,9 +29,15 @@ module MusicBrainz
           return ''
         end
       end
-    
+
     end
     
+    # A specification on how much data to return with an artist.
+    # 
+    # The MusicBrainz server only supports some combinations of release types
+    # for the releases and vaReleases include tags. At the moment, not more
+    # than two release types should be selected, while one of them has to be
+    # Release.TYPE_OFFICIAL, Release.TYPE_PROMOTION or Release.TYPE_BOOTLEG.
     class ArtistIncludes < AbstractIncludes
     
       # Includes is a hash with the following fields:
@@ -32,20 +45,26 @@ module MusicBrainz
       # [:releases]     Array of release types that should be included
       #                 in the result. All releases of the artist that match
       #                 all of those types will be included. Use the constants
-      #                 defined in Model::Releases for the release types.
+      #                 defined in Model::Release for the release types.
       # [:va_releases]  Array of release types. All various artist releases
       #                 the artist appears on and that match all of those
       #                 types will be included. Use the constants
-      #                 defined in Model::Releases for the release types.
+      #                 defined in Model::Release for the release types.
       # [:artist_rels]  Include artist relationships (boolean).
       # [:release_rels] Include release relationships (boolean).
       # [:track_rels]   Include track relationships (boolean).
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
+      # [:tags]         Include tags (boolean).
       # 
-      # TODO: Check release types. It's possible that :releases
-      # and :va_releases can't be used in parallel.
+      #--
+      # TODO:: Check release types. It's possible that :releases
+      #        and :va_releases can't be used in parallel.
+      #++
       def initialize(includes)
+        Utils.check_options includes, 
+          :aliases, :artist_rels, :release_rels, :track_rels, 
+          :label_rels, :url_rels, :tags, :releases, :va_releases
         @parameters = Array.new
         @parameters << 'aliases'      if includes[:aliases]
         @parameters << 'artist-rels'  if includes[:artist_rels]
@@ -53,6 +72,7 @@ module MusicBrainz
         @parameters << 'track-rels'   if includes[:track_rels]
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
+        @parameters << 'tags'         if includes[:tags]
         
         includes[:releases].each {|release_type|
           @parameters << 'sa-' + release_type.to_s
@@ -65,6 +85,7 @@ module MusicBrainz
       
     end
     
+    # A specification on how much data to return with a release.
     class ReleaseIncludes < AbstractIncludes
     
       # Includes is a hash with the following fields:
@@ -74,7 +95,7 @@ module MusicBrainz
       # [:discs]        Include the disc IDs (boolean).
       # [:tracks]       Include the release tracks (boolean).
       # [:labels]       Include the labels under which the release
-      #                 was publlished (boolean).
+      #                 was published (boolean).
       # [:artist_rels]  Include artist relationships (boolean).
       # [:release_rels] Include release relationships (boolean).
       # [:track_rels]   Include track relationships (boolean).
@@ -82,7 +103,12 @@ module MusicBrainz
       # [:url_rels]     Include url relationships (boolean).
       # [:track_level_rels] Include the relationships for the
       #                     single tracks as well (boolean).
+      # [:tags]         Include tags (boolean).
       def initialize(includes)
+        Utils.check_options includes, 
+            :artist, :counts, :release_events, :discs, :tracks, 
+            :labels, :artist_rels, :release_rels, :track_rels, 
+            :label_rels, :url_rels, :track_level_rels, :tags
         @parameters = Array.new
         @parameters << 'artist'       if includes[:artist]
         @parameters << 'counts'       if includes[:counts]
@@ -96,10 +122,12 @@ module MusicBrainz
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
         @parameters << 'track-level-rels' if includes[:track_level_rels]
+        @parameters << 'tags'         if includes[:tags]
       end
     
     end
     
+    # A specification on how much data to return with a track.
     class TrackIncludes < AbstractIncludes
     
       # Includes is a hash with the following fields:
@@ -111,7 +139,11 @@ module MusicBrainz
       # [:track_rels]   Include track relationships (boolean).
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
+      # [:tags]         Include tags (boolean).
       def initialize(includes)
+        Utils.check_options includes, 
+            :artist, :releases, :puids, :artist_rels, :release_rels, 
+            :track_rels, :label_rels, :url_rels, :tags
         @parameters = Array.new
         @parameters << 'artist'       if includes[:artist]
         @parameters << 'releases'     if includes[:releases]
@@ -121,10 +153,12 @@ module MusicBrainz
         @parameters << 'track-rels'   if includes[:track_rels]
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
+        @parameters << 'tags'         if includes[:tags]
       end
     
     end
     
+    # A specification on how much data to return with a label.
     class LabelIncludes < AbstractIncludes
     
       # Includes is a hash with the following fields:
@@ -134,7 +168,11 @@ module MusicBrainz
       # [:track_rels]   Include track relationships (boolean).
       # [:label_rels]   Include label relationships (boolean).
       # [:url_rels]     Include url relationships (boolean).
+      # [:tags]         Include tags (boolean).
       def initialize(includes)
+        Utils.check_options includes, 
+            :aliases, :artist_rels, :release_rels, 
+            :track_rels, :label_rels, :url_rels, :tags
         @parameters = Array.new
         @parameters << 'aliases'      if includes[:aliases]
         @parameters << 'artist-rels'  if includes[:artist_rels]
@@ -142,6 +180,7 @@ module MusicBrainz
         @parameters << 'track-rels'   if includes[:track_rels]
         @parameters << 'label-rels'   if includes[:label_rels]
         @parameters << 'url-rels'     if includes[:url_rels]
+        @parameters << 'tags'         if includes[:tags]
       end
     
     end