rbrainz 0.4.2 → 0.5.0

data/lib/rbrainz/webservice/query.rb

@@ -1,4 +1,5 @@
-# $Id: query.rb 218 2008-09-02 07:45:33Z phw $
+# -*- coding: utf-8 -*-
+# $Id: query.rb 270 2009-05-24 22:15:29Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -179,7 +180,7 @@ module MusicBrainz
       # or a options hash as expected by ArtistIncludes.
       # 
       # If no artist with that ID can be found, include contains invalid tags
-      # or there's a server problem, and exception is raised.
+      # or there's a server problem, an exception is raised.
       # 
       # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
       def get_artist_by_id(id, includes = nil)
@@ -187,10 +188,10 @@ module MusicBrainz
         return get_entity_by_id(Model::Artist.entity_type, id, includes)
       end
       
-      # Returns artists matching given criteria.
+      # Returns artists matching the given criteria.
       # 
       # The parameter _filter_ must be an instance of ArtistFilter
-      # or a options hash as expected by ArtistFilter.
+      # or an option hash as expected by ArtistFilter.
       # 
       # Raises:: ConnectionError, RequestError, ResponseError
       def get_artists(filter)
@@ -198,13 +199,38 @@ module MusicBrainz
         return get_entities(Model::Artist.entity_type, filter)
       end
       
-      # Returns an release.
+      # Returns a release group.
+      # 
+      # The parameter _includes_ must be an instance of ReleaseGroupIncludes
+      # or a options hash as expected by ReleaseGroupIncludes.
+      # 
+      # If no release group with that ID can be found, include contains invalid
+      # tags or there's a server problem, an exception is raised.
+      # 
+      # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
+      def get_release_group_by_id(id, includes = nil)
+        includes = ReleaseGroupIncludes.new(includes) unless includes.nil? || includes.is_a?(ReleaseGroupIncludes)
+        return get_entity_by_id(Model::ReleaseGroup.entity_type, id, includes)
+      end
+      
+      # Returns release groups matching the given criteria.
+      # 
+      # The parameter _filter_ must be an instance of ReleaseGroupFilter
+      # or an option hash as expected by ReleaseGroupFilter.
+      # 
+      # Raises:: ConnectionError, RequestError, ResponseError
+      def get_release_groups(filter)
+        filter = ReleaseGroupFilter.new(filter) unless filter.nil? || filter.is_a?(ReleaseGroupFilter)
+        return get_entities(Model::ReleaseGroup.entity_type, filter)
+      end
+      
+      # Returns a release.
       # 
       # The parameter _includes_ must be an instance of ReleaseIncludes
       # or a options hash as expected by ReleaseIncludes.
       # 
       # If no release with that ID can be found, include contains invalid tags
-      # or there's a server problem, and exception is raised.
+      # or there's a server problem, an exception is raised.
       # 
       # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
       def get_release_by_id(id, includes = nil)
@@ -212,10 +238,10 @@ module MusicBrainz
         return get_entity_by_id(Model::Release.entity_type, id, includes)
       end
       
-      # Returns releases matching given criteria.
+      # Returns releases matching the given criteria.
       # 
       # The parameter _filter_ must be an instance of ReleaseFilter
-      # or a options hash as expected by ReleaseFilter.
+      # or an option hash as expected by ReleaseFilter.
       # 
       # Raises:: ConnectionError, RequestError, ResponseError
       def get_releases(filter)
@@ -223,13 +249,13 @@ module MusicBrainz
         return get_entities(Model::Release.entity_type, filter)
       end
       
-      # Returns an track.
+      # Returns a track.
       # 
       # The parameter _includes_ must be an instance of TrackIncludes
       # or a options hash as expected by TrackIncludes.
       # 
       # If no track with that ID can be found, include contains invalid tags
-      # or there's a server problem, and exception is raised.
+      # or there's a server problem, an exception is raised.
       # 
       # Raises:: ConnectionError, RequestError, ResourceNotFoundError, ResponseError
       def get_track_by_id(id, includes = nil)
@@ -237,10 +263,10 @@ module MusicBrainz
         return get_entity_by_id(Model::Track.entity_type, id, includes)
       end
       
-      # Returns tracks matching given criteria.
+      # Returns tracks matching the given criteria.
       # 
       # The parameter _filter_ must be an instance of TrackFilter
-      # or a options hash as expected by TrackFilter.
+      # or an option hash as expected by TrackFilter.
       # 
       # Raises:: ConnectionError, RequestError, ResponseError
       def get_tracks(filter)
@@ -295,7 +321,7 @@ module MusicBrainz
       # Submit track to PUID mappings.
       #
       # The <em>tracks2puids</em> parameter has to be a Hash or Array
-      # with track ID/PUID pairs. The track IDs are either instances of MBID,
+      # with track ID/PUID pairs. The track IDs are either instances of Model::MBID,
       # absolute URIs or the 36 character ASCII representation. PUIDs are 
       # 36 characters ASCII strings.
       # 
@@ -333,9 +359,59 @@ module MusicBrainz
         @webservice.post(:track, :params=>params)
       end
       
-      # Submit tags for an entity. _mbid_ must be an instance of MBID identifying
+      # Submit track to ISRC mappings.
+      #
+      # The <em>tracks2isrcs</em> parameter has to be a Hash or Array
+      # with track ID/ISRC pairs. The track IDs are either instances of Model::MBID,
+      # absolute URIs or the 36 character ASCII representation. ISRCs are either
+      # instances of Model::ISRC or 12 character ASCII strings.
+      # 
+      # Example:
+      #  ws = Webservice::Webservice.new(
+      #         :host     => 'test.musicbrainz.org',
+      #         :username => 'outsidecontext',
+      #         :password => 'secret'
+      #  ) 
+      #  
+      #  query = Webservice::Query.new(ws, :client_id=>'My Tagging App 1.0')
+      #  
+      #  query.submit_isrcs([
+      #    ['7f574ec1-344c-4ae1-970d-3c757f9a717e', 'DED830049301'],
+      #    ['1393122c-364c-4fb6-9a4b-17eddce90152', 'DED830049302'],
+      #    ['2634965c-5299-4958-b0dc-47b166bb6898', 'DED830049303'],
+      #    ['dad6b8a4-0412-4a80-9123-3e0ebddaf82d', 'DED830049304'],
+      #    ['e1f7e805-33f3-4663-b294-3805b82405f9', 'DED830049305'],
+      #    ['d9f932ad-de0d-44ca-bf35-ae8184f63909', 'DED830049306'],
+      #    ['c983b62d-f528-433f-a402-a6317ce3d2d8', 'DED830049307'],
+      #    ['9d50b06a-4136-427f-8d11-b2efb0141da6', 'DED830049308'],
+      #    ['f2af3e3f-3f9f-4f8d-8b60-1d1b709aaf69', 'DED830049309'],
+      #    ['059384bc-fb45-445e-ab77-950d6ccf587a', 'DED830049310'],
+      #    ['2f4d7b47-a4ba-495a-b447-60b8287ed9c9', 'DED830049311'],
+      #  ])
+      #
+      # Note that this method only works if a valid user name and
+      # password have been set. If username and/or password are incorrect,
+      # an AuthenticationError is raised. See the example in Query on
+      # how to supply authentication data.
+      #
+      # See:: http://musicbrainz.org/doc/ISRC
+      # Raises:: ConnectionError, RequestError, AuthenticationError, InvalidISRCError
+      def submit_isrcs(tracks2isrcs)
+        raise RequestError, 'Please supply a client ID' unless @client_id
+        params = [['client', @client_id.to_s]] # Encoded as utf-8
+
+        tracks2isrcs.each do |track_id, isrc|
+          track_id = Model::MBID.parse(track_id, :track).uuid
+          isrc = Model::ISRC.parse(isrc)
+          params << ['isrc', track_id + ' ' + isrc.to_str ]
+        end
+
+        @webservice.post(:track, :params=>params)
+      end
+      
+      # Submit tags for an entity. _mbid_ must be an instance of Model::MBID identifying
       # the entity the tag should applied to and _tags_ is either and array or
-      # Collection of Tag objects or a string with comma separated tags.
+      # Collection of Model::Tag objects or a string with comma separated tags.
       # 
       # Note that this method only works if a valid user name and password have
       # been set. The tags will be applied for the authenticated user. If
@@ -395,6 +471,70 @@ module MusicBrainz
         return get_entities(:tag, "entity=#{mbid.entity}&id=#{mbid.uuid}").to_collection
       end
       
+      # Submit the user's rating for an entity. _mbid_ must be an instance of
+      # Model::MBID identifying the entity which should be rated and _rating_ is
+      # either a Model::Rating object or an integer value between 0 and 5.
+      # 
+      # Note that this method only works if a valid user name and password have
+      # been set. The tags will be applied for the authenticated user. If
+      # username and/or password are incorrect, an AuthenticationError is raised.
+      # See the example in Query on how to supply authentication data.
+      #
+      # Example:
+      #  ws = Webservice::Webservice.new(
+      #         :host     => 'test.musicbrainz.org',
+      #         :username => 'outsidecontext',
+      #         :password => 'secret'
+      #  ) 
+      #  
+      #  query = Webservice::Query.new(ws)
+      #
+      #  mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0')
+      #  query.submit_user_rating(mbid, 5)
+      # 
+      # See:: Model::Rating
+      # Raises:: ConnectionError, RequestError, AuthenticationError
+      def submit_user_rating(mbid, rating)
+        mbid = Model::MBID.parse(mbid)
+        params = {:entity=>mbid.entity, :id=>mbid.uuid, :rating=>rating.to_i}
+        @webservice.post(:rating, :params=>params)
+      end
+      
+      # Returns the Model::Rating a user has applied to the entity
+      # identified by _mbid_.
+      # 
+      # Note that this method only works if a valid user name and password have
+      # been set. Only the tags the authenticated user applied to the entity will
+      # be returned. If username and/or password are incorrect, an
+      # AuthenticationError is raised. See the example in Query on how to supply
+      # authentication data.
+      #
+      # Example:
+      #  ws = Webservice::Webservice.new(
+      #         :host     => 'test.musicbrainz.org',
+      #         :username => 'outsidecontext',
+      #         :password => 'secret'
+      #  ) 
+      #  
+      #  query = Webservice::Query.new(ws)
+      #
+      #  mbid = Model::MBID.new('http://musicbrainz.org/artist/10bf95b6-30e3-44f1-817f-45762cdc0de0')
+      #  rating = query.get_user_rating(mbid)
+      # 
+      # See:: Model::Rating
+      # Raises:: ConnectionError, RequestError, ResponseError, AuthenticationError
+      def get_user_rating(mbid)
+        mbid = Model::MBID.parse(mbid)
+        stream = @webservice.get(:rating, :filter => "entity=#{mbid.entity}&id=#{mbid.uuid}")
+        begin
+          rating = MBXML.new(stream, @factory).get_entity(:user_rating)
+        rescue MBXML::ParseError => e
+          raise ResponseError, e.to_s
+        end
+        rating = Model::Rating.new unless rating
+        return rating
+      end
+      
       private # ----------------------------------------------------------------
       
       # Helper method which will return any entity by ID.
@@ -430,4 +570,4 @@ module MusicBrainz
     end
 
   end
-end
+end

data/lib/rbrainz/webservice/webservice.rb

@@ -1,4 +1,4 @@
-# $Id: webservice.rb 209 2008-06-22 21:53:55Z phw $
+# $Id: webservice.rb 277 2009-05-25 19:33:26Z phw $
 #
 # Author::    Philipp Wolfer (mailto:phw@rubyforge.org)
 # Copyright:: Copyright (c) 2007, Nigel Graham, Philipp Wolfer
@@ -72,7 +72,7 @@ module MusicBrainz
       # [:username] The username to authenticate with.
       # [:password] The password to authenticate with.
       # [:user_agent] Value sent in the User-Agent HTTP header. Defaults to "rbrainz/#{RBRAINZ_VERSION}"
-      # [:proxy] URL for the proxy server to connect through
+      # [:proxy] URI for the proxy server to connect through
       def initialize(options={ :host=>nil, :port=>nil, :path_prefix=>'/ws', :username=>nil, :password=>nil, :user_agent=>"rbrainz/#{RBRAINZ_VERSION}", :proxy=>nil })
         Utils.check_options options, :host, :port, :path_prefix, :username, :password, :user_agent, :proxy
         @host = options[:host] ? options[:host] : 'musicbrainz.org'
@@ -83,14 +83,7 @@ module MusicBrainz
         @user_agent = options[:user_agent] ? options[:user_agent] : "rbrainz/#{RBRAINZ_VERSION}"
         @open_timeout = nil
         @read_timeout = nil
-        @proxy = {}
-        unless options[:proxy].nil?
-          uri = URI.parse( options[:proxy] )
-          @proxy[:host], @proxy[:port] = uri.host, uri.port
-          if uri.userinfo
-            @proxy[:username], @proxy[:password] = uri.userinfo.split(/:/)
-          end
-        end
+        set_proxy_options(options)
       end
     
       # Query the Webservice with HTTP GET.
@@ -108,55 +101,9 @@ module MusicBrainz
       # See:: IWebservice#get
       def get(entity_type, options={ :id=>nil, :include=>nil, :filter=>nil, :version=>1 })
         Utils.check_options options, :id, :include, :filter, :version
-        url = URI.parse(create_uri(entity_type, options))
-        request = Net::HTTP::Get.new(url.request_uri)
-        request['User-Agent'] = @user_agent
-        connection = Net::HTTP.new(url.host, url.port, @proxy[:host], @proxy[:port])
-        
-        # Set timeouts
-        connection.open_timeout = @open_timeout if @open_timeout
-        connection.read_timeout = @read_timeout if @read_timeout
-        
-        # Make the request
-        begin
-          response = connection.start do |http|
-            response = http.request(request)
-            if response.is_a?(Net::HTTPProxyAuthenticationRequired) && @proxy[:username] && @proxy[:password]
-              request = Net::HTTP::Post.new(url.request_uri)
-              request['User-Agent'] = @user_agent
-              request.proxy_select_auth(@proxy[:username], @proxy[:password], response)
-              request.set_form_data(options[:params])
-              response = http.request(request)
-            end
-
-            if response.is_a?(Net::HTTPUnauthorized) && @username && @password
-              request = Net::HTTP::Get.new(url.request_uri)
-              request['User-Agent'] = @user_agent
-              request.select_auth @username, @password, response
-              response = http.request(request)
-            end
-            response
-          end
-        rescue Timeout::Error, Errno::ETIMEDOUT
-          raise ConnectionError.new('%s timed out' % url.to_s)
-        rescue SocketError => e
-          raise ConnectionError.new('%s (%s)' % [url.to_s, e.to_s])
-        end
-        
-        # Handle response errors.
-        if response.is_a? Net::HTTPBadRequest # 400
-          raise RequestError.new(url.to_s)
-        elsif response.is_a? Net::HTTPUnauthorized # 401
-          raise AuthenticationError.new(url.to_s)
-        elsif response.is_a? Net::HTTPNotFound # 404
-          raise ResourceNotFoundError.new(url.to_s)
-        elsif response.is_a? Net::HTTPForbidden 
-          raise AuthenticationError.new(url.to_s)
-        elsif not response.is_a? Net::HTTPSuccess
-          raise ConnectionError.new(response.class.name)
-        end
-        
-        return ::StringIO.new(response.body)
+        uri = create_uri(entity_type, options)
+        response = open_connection_and_make_request(uri, :get)
+        return response
       end
       
       # Send data to the web service via HTTP-POST.
@@ -177,68 +124,35 @@ module MusicBrainz
       # See:: IWebservice#post
       def post(entity_type, options={ :id=>nil, :params=>[], :version=>1 })
         Utils.check_options options, :id, :params, :version
-        url = URI.parse(create_uri(entity_type, options))
-        request = Net::HTTP::Post.new(url.request_uri)
-        request['User-Agent'] = @user_agent
-        request.set_form_data(options[:params])
-        connection = Net::HTTP.new(url.host, url.port, @proxy[:host], @proxy[:port])
-        
-        # Set timeouts
-        connection.open_timeout = @open_timeout if @open_timeout
-        connection.read_timeout = @read_timeout if @read_timeout
-        
-        # Make the request
-        begin
-          response = connection.start do |http|
-            response = http.request(request)
-            
-            if response.is_a?(Net::HTTPProxyAuthenticationRequired) && @proxy[:username] && @proxy[:password]
-              request = Net::HTTP::Post.new(url.request_uri)
-              request['User-Agent'] = @user_agent
-              request.proxy_select_auth(@proxy[:username], @proxy[:password], response)
-              request.set_form_data(options[:params])
-              response = http.request(request)
-            end
-            if response.is_a?(Net::HTTPUnauthorized) && @username && @password
-              request = Net::HTTP::Post.new(url.request_uri)
-              request['User-Agent'] = @user_agent
-              request.select_auth( @username, @password, response)
-              request.set_form_data(options[:params])
-              response = http.request(request)
-            end
-            response
-          end
-        rescue Timeout::Error, Errno::ETIMEDOUT
-          raise ConnectionError.new('%s timed out' % url.to_s)
-        rescue SocketError => e
-          raise ConnectionError.new('%s (%s)' % [url.to_s, e.to_s])
-        end
-        
-        # Handle response errors.
-        if response.is_a? Net::HTTPBadRequest # 400
-          raise RequestError.new(url.to_s)
-        elsif response.is_a? Net::HTTPUnauthorized # 401
-          raise AuthenticationError.new(url.to_s)
-        elsif response.is_a? Net::HTTPNotFound # 404
-          raise ResourceNotFoundError.new(url.to_s)
-        elsif response.is_a? Net::HTTPForbidden 
-          raise AuthenticationError.new(url.to_s)
-        elsif not response.is_a? Net::HTTPSuccess
-          raise ConnectionError.new(response.class.name)
-        end
-        
-        return ::StringIO.new(response.body)
+        uri = create_uri(entity_type, options)
+        response = open_connection_and_make_request(uri, :post, options[:params])
+        return response
       end
       
       private # ----------------------------------------------------------------
       
+      def set_proxy_options(options)
+        @proxy = {}
+        unless options[:proxy].nil?
+          uri = URI.parse( options[:proxy] )
+          @proxy[:host], @proxy[:port] = uri.host, uri.port
+          if uri.userinfo
+            @proxy[:username], @proxy[:password] = uri.userinfo.split(/:/)
+          end
+        end
+      end
+      
       # Builds a request URI for querying the webservice.
-      def create_uri(entity_type, options = {:id=>nil, :include=>nil, :filter=>nil, :version=>1, :type=>nil})
+      def create_uri(entity_type, options = {:id=>nil, :include=>nil, :filter=>nil, :version=>1, :type=>'xml'})
         # Make sure the version is set
         options[:version] = 1 if options[:version].nil?
         options[:type] = 'xml' if options[:type].nil?
-        
-        # Build the URI
+        uri = build_uri_without_querystring(entity_type, options)
+        uri = append_querystring_to_uri(uri, options)
+        return URI.parse(uri)
+      end
+      
+      def build_uri_without_querystring(entity_type, options)
         if options[:id]
           # Make sure the id is a MBID object
           id = options[:id]
@@ -252,14 +166,88 @@ module MusicBrainz
           uri = 'http://%s:%d%s/%d/%s/' %
                 [@host, @port, @path_prefix, options[:version], entity_type]
         end
-        
-        # Append the querystring
+        return uri
+      end
+      
+      def append_querystring_to_uri(uri, options)
         querystring = []
         querystring << 'type=' + CGI.escape(options[:type]) unless options[:type].nil?
         querystring << options[:include].to_s unless options[:include].nil?
         querystring << options[:filter].to_s unless options[:filter].nil?
         uri += '?' + querystring.join('&') unless querystring.empty? 
-        return uri
+      end
+      
+      def open_connection_and_make_request(uri, request_type, form_data=nil)
+        connection = create_connection(uri)
+        response = make_request(connection, uri, request_type, form_data)
+        handle_response_errors(uri, response)
+        return ::StringIO.new(response.body)  
+      end
+      
+      def create_connection(uri)
+        connection = Net::HTTP.new(uri.host, uri.port, @proxy[:host], @proxy[:port])
+        set_connection_timeouts(connection)
+        return connection
+      end
+      
+      def make_request(connection, uri, request_type, form_data=nil)
+        response = nil
+        begin
+          connection.start do |http|
+            request = create_request(uri, request_type, form_data)
+            response = http.request(request)
+            if response.is_a?(Net::HTTPProxyAuthenticationRequired) && @proxy[:username] && @proxy[:password]
+              request = create_request(uri, request_type, form_data)
+              request.proxy_select_auth(@proxy[:username], @proxy[:password], response)
+              response = http.request(request)
+            end
+
+            if response.is_a?(Net::HTTPUnauthorized) && @username && @password
+              request = create_request(uri, request_type, form_data)
+              request.select_auth @username, @password, response
+              response = http.request(request)
+            end
+            response
+          end
+        rescue Timeout::Error, Errno::ETIMEDOUT
+          raise ConnectionError.new('%s timed out' % uri.to_s)
+        rescue SocketError => e
+          raise ConnectionError.new('%s (%s)' % [uri.to_s, e.to_s])
+        rescue ::Exception => e
+          raise ConnectionError.new(e.to_s) 
+        end
+        return response
+      end
+      
+      def set_connection_timeouts(connection)
+        connection.open_timeout = @open_timeout if @open_timeout
+        connection.read_timeout = @read_timeout if @read_timeout
+      end
+      
+      def create_request(uri, request_type, form_data=nil)
+        if request_type == :post
+          request = Net::HTTP::Post.new(uri.request_uri)
+        else
+          request = Net::HTTP::Get.new(uri.request_uri)
+        end
+        request['User-Agent'] = @user_agent
+        request.set_form_data(form_data) unless form_data.nil?
+        return request
+      end
+      
+      # Handles response errors and raises appropriate exceptions
+      def handle_response_errors(uri, response)
+        if response.is_a? Net::HTTPBadRequest # 400
+          raise RequestError.new(uri.to_s)
+        elsif response.is_a? Net::HTTPUnauthorized # 401
+          raise AuthenticationError.new(uri.to_s)
+        elsif response.is_a? Net::HTTPNotFound # 404
+          raise ResourceNotFoundError.new(uri.to_s)
+        elsif response.is_a? Net::HTTPForbidden 
+          raise AuthenticationError.new(uri.to_s)
+        elsif not response.is_a? Net::HTTPSuccess
+          raise ConnectionError.new(response.class.name)
+        end
       end
     
     end