datasift 1.5.0 → 2.0.0

data/lib/DataSift/stream_consumer.rb

@@ -1,46 +1,43 @@
-#
-# stream_consumer.rb - This file contains the StreamConsumer class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The StreamConsumer class is base class for various stream consumers.
-
 module DataSift
-
-	# StreamConsumer class.
-	#
+	#This is the base class for all StreamConsumer implementation.
 	class StreamConsumer
+		#Constant for the HTTP StreamConsumer implementation option.
 		TYPE_HTTP = 'HTTP'
 
+		#Constant for the "stopped" status.
 		STATE_STOPPED = 0
+		#Constant for the "starting" status.
 		STATE_STARTING = 1
+		#Constant for the "running" status.
 		STATE_RUNNING = 2
+		#Constant for the "stopping" status.
 		STATE_STOPPING = 3
 
-		# Factory function. Creates a StreamConsumer-derived object for the given
-		# type.
-		# === Parameters
-		#
-		# * +type+ - Use the TYPE_ constants
-		# * +definition+ - CSDL string or a Definition object.
-		#
+		#Factory function. Creates a StreamConsumer-derived object for the given
+		#type.
+		#=== Parameters
+		#* +type+ - Use the TYPE_ constants
+		#* +definition+ - CSDL string or a Definition object.
+		#=== Returns
+		#A StreamConsumer-derived object.
 		def self.factory(user, type, definition)
 			type ||= TYPE_HTTP
 			@klass = Module.const_get('DataSift').const_get('StreamConsumer_' + type)
 			@klass.new(user, definition)
 		end
 
+		#Whether the consumer should automatically try to reconnect if the
+		#connection is dropped.
 		attr_accessor :auto_reconnect
-		attr_reader :state, :stop_reason
-
-		# Constructor. Do not use this directly, use the factory method instead.
-		# === Parameters
-		#
-		# * +user+ - The user this consumer will run as.
-		# * +definition+ - CSDL string or a Definition object.
-		#
+		#The current state of the consumer.
+		attr_reader :state
+		#The reason the consumer was stopped.
+		attr_reader :stop_reason
+
+		#Constructor. Do not use this directly, use the factory method instead.
+		#=== Parameters
+		#* +user+ - The user this consumer will run as.
+		#* +definition+ - CSDL string or a Definition object.
 		def initialize(user, definition)
 			raise InvalidDataError, 'Please supply a valid User object when creating a Definition object.' unless user.is_a? DataSift::User
 
@@ -61,11 +58,9 @@ module DataSift
 			@definition.hash
 		end
 
-		# This is called when a deletion notification is received.
-		# === Parameters
-		#
-		# * +interaction+ - Minimal details about the interaction that was deleted.
-		#
+		#Called when a deletion notification is received.
+		#=== Parameters
+		#* +interaction+ - Minimal details about the interaction that was deleted.
 		def onDeleted(&block)
 			if block_given?
 				@on_deleted = block
@@ -75,11 +70,9 @@ module DataSift
 			end
 		end
 
-		# This is called when an error message is received.
-		# === Parameters
-		#
-		# * +message+ - The error message.
-		#
+		#This is called when an error message is received.
+		#=== Parameters
+		#* +message+ - The error message.
 		def onError(&block)
 			if block_given?
 				@on_error = block
@@ -89,11 +82,9 @@ module DataSift
 			end
 		end
 
-		# This is called when an error message is received.
-		# === Parameters
-		#
-		# * +message+ - The error message.
-		#
+		#This is called when an error message is received.
+		#=== Parameters
+		#* +message+ - The error message.
 		def onWarning(&block)
 			if block_given?
 				@on_warning = block
@@ -103,11 +94,9 @@ module DataSift
 			end
 		end
 
-		# This is called when the consumer is stopped.
-		# === Parameters
-		#
-		# * +reason+ - The reason why the consumer stopped.
-		#
+		#This is called when the consumer is stopped.
+		#=== Parameters
+		#* +reason+ - The reason why the consumer stopped.
 		def onStopped(&block)
 			if block_given?
 				@on_stopped = block
@@ -117,14 +106,12 @@ module DataSift
 			end
 		end
 
-		# Once an instance of a StreamConsumer is ready for use, call this to
-		# start consuming. Extending classes should implement onStart to handle
-		# actually starting.
-		# === Parameters
-		#
-		# * +auto_reconnect+ - Whether the consumer should automatically reconnect.
-		# * +block+ - An optional block to receive incoming interactions.
-		#
+		#Once an instance of a StreamConsumer is ready for use, call this to
+		#start consuming. Extending classes should implement onStart to handle
+		#actually starting.
+		#=== Parameters
+		#* +auto_reconnect+ - Whether the consumer should automatically reconnect.
+		#* +block+ - An optional block to receive incoming interactions.
 		def consume(auto_reconnect = true, &block)
 			@auto_reconnect = auto_reconnect;
 
@@ -149,29 +136,25 @@ module DataSift
 			end
 		end
 
-		# Called when the consumer should start consuming the stream.
-		#
+		#Called when the consumer should start consuming the stream.
 		def onStart()
-			puts 'onStart method has not been overridden!'
+			abort('onStart method has not been overridden!')
 		end
 
-		# This method can be called at any time to *request* that the consumer
-		# stop consuming. This method sets the state to STATE_STOPPING and it's
-		# up to the consumer implementation to notice that this has changed, stop
-		# consuming and call the onStopped method.
-		#
+		#This method can be called at any time to *request* that the consumer
+		#stop consuming. This method sets the state to STATE_STOPPING and it's
+		#up to the consumer implementation to notice that this has changed, stop
+		#consuming and call the onStopped method.
 		def stop()
 			raise InvalidDataError, 'Consumer state must be RUNNING before it can be stopped' unless @state = StreamConsumer::STATE_RUNNING
 			@state = StreamConsumer::STATE_STOPPING
 		end
 
-		# Default implementation of onStop. It's unlikely that this method will
-		# ever be used in isolation, but rather it should be called as the final
-		# step in the extending class's implementation.
-		# === Parameters
-		#
-		# * +reason+ - The reason why the consumer stopped.
-		#
+		#Default implementation of onStop. It's unlikely that this method will
+		#ever be used in isolation, but rather it should be called as the final
+		#step in the extending class's implementation.
+		#=== Parameters
+		#* +reason+ - The reason why the consumer stopped.
 		def onStop(reason = '')
 			reason = 'Unexpected' unless @state != StreamConsumer::STATE_STOPPING and reason.length == 0
 			@state = StreamConsumer::STATE_STOPPED

data/lib/DataSift/stream_consumer_http.rb

@@ -1,12 +1,3 @@
-#
-# stream_consumer_http.rb - This file contains the StreamConsumer_HTTP class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The StreamConsumer_HTTP class implements HTTP streaming.
-
 $LOAD_PATH.unshift(File.dirname(__FILE__) + '/../')
 
 require 'uri'
@@ -15,14 +6,19 @@ require 'yajl'
 require 'cgi'
 
 module DataSift
-
+	#The HTTP implementation of the StreamConsumer.
 	class StreamConsumer_HTTP < StreamConsumer
-
-		# Constructor. Requires valid user and definition objects.
+		#Constructor. Requires valid user and definition objects.
+		#=== Parameters
+		#* +user+ - The user consuming the data.
+		#* +definition+ - The Definition to consume.
 		def initialize(user, definition)
 			super
 		end
 
+		#Called when the consumer is started.
+		#=== Parameters
+		#* +block+ - A block to receive incoming data.
 		def onStart(&block)
 			begin
 				reconnect() unless !@socket.nil? and !@socket.closed?
@@ -85,8 +81,9 @@ module DataSift
 			onStop(@stop_reason)
 		end
 
-	  private
+  private
 
+  	#Reconnect the stream socket.
 		def reconnect()
 			uri = URI.parse('http' + (@user.use_ssl ? 's' : '') + '://' + User::STREAM_BASE_URL + @definition.hash)
 
@@ -175,11 +172,10 @@ module DataSift
 			end while @state != StreamConsumer::STATE_RUNNING
 		end
 
+		#Disconnect the stream socket.
 		def disconnect()
 			@socket.close if !@socket.nil? and !@socket.closed?
 			@raw_socket.close if !@raw_socket.nil? and !@raw_socket.closed?
 		end
-
 	end
-
 end

data/lib/DataSift/user.rb

@@ -1,36 +1,36 @@
-#
-# user.rb - This file contains the User class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The User class represents a user of the API. Applications should start their
-# API interactions by creating an instance of this class. Once initialised it
-# provides factory methods for all of the functionality in the API.
-
+#This is the official DataSift client library for Ruby.
 module DataSift
-	# User class.
-	#
-	# == Introduction
-	#
-	# The User class represents a user of the API. Applications should start their
-	# API interactions by creating an instance of this class. Once initialised it
-	# provides factory methods for all of the functionality in the API.
-	#
+	#The User class represents a user of the API. Applications should start their
+	#API interactions by creating an instance of this class. Once initialised it
+	#provides factory methods for all of the functionality in the API.
 	class User
+		#The user agent to pass through with all HTTP requests.
 		USER_AGENT = 'DataSiftRuby/' + File.open(File.dirname(File.dirname(File.dirname(__FILE__))) + '/VERSION').first;
+		#The base URL for API requests.
 		API_BASE_URL = 'api.datasift.com/';
+		#The base URL for streams.
 		STREAM_BASE_URL = 'stream.datasift.com/';
 
-		attr_reader :username, :api_key, :rate_limit, :rate_limit_remaining, :api_client, :use_ssl
+		#The User's DataSift username.
+		attr_reader :username
+		#The User's DataSift API key.
+		attr_reader :api_key
+		#The User's total number of available hourly API credits. This is not
+		#populated until an API request is made.
+		attr_reader :rate_limit
+		#The User's API credits remaining. This is not populated until an API
+		#request is made.
+		attr_reader :rate_limit_remaining
+		#The APIClient class to use when making API requests.
+		attr_reader :api_client
+		#True if streaming connections should use SSL.
+		attr_reader :use_ssl
 
-		# Constructor. A username and API key are required when constructing an
-		# instance of this class.
-		# === Parameters
-		#
-		# * +username+ - The user's username
-		# * +api_key+ - The user's API key
+		#Constructor. A username and API key are required when constructing an
+		#instance of this class.
+		#=== Parameters
+		#* +username+ - The User's DataSift username
+		#* +api_key+ - The User's DataSift API key
 		def initialize(username, api_key, use_ssl = true)
 			username.strip!
 			api_key.strip!
@@ -44,65 +44,191 @@ module DataSift
 			@use_ssl = use_ssl
 		end
 
-		# Creates and returns a definition object.
-		# === Parameters
-		#
-		# * +csdl+ - Optional CSDL string with which to prime the object.
+		#Creates and returns a definition object.
+		#=== Parameters
+		#* +csdl+ - Optional CSDL string with which to prime the object.
+		#=== Returns
+		#A Definition object.
 		def createDefinition(csdl = '')
 			DataSift::Definition.new(self, csdl, false)
 		end
 
-		# Returns a StreamConsumer-derived object for the given hash, for the
-		# given type.
-		# === Parameters
-		#
-		# * +type+ - The consumer type for which to construct a consumer.
-		# * +hash+ - The hash to be consumed.
-		#
+		#Create a Historics query based on this Definition.
+		#=== Parameters
+		#* +hash+ - The stream hash for a new Historics query.
+		#* +start_date+ - The start date for a new Historics query.
+		#* +end_date+ - The end date for a new Historics query.
+		#* +sources+ - An array of sources for a new Historics query.
+		#* +name+ - The name for a new Historics query.
+		#* +sample+ - The sample rate for the new Historics query.
+		#=== Returns
+		#A Historic object.
+		def createHistoric(hash, start_date, end_date, sources, sample, name)
+			return Historic.new(self, hash, start_date, end_date, sources, sample, name)
+		end
+
+		#Get a Historics query from the API.
+		#=== Parameters
+		#* +playback_id+ - The playback ID of the Historics query to retrieve.
+		#=== Returns
+		#A Historic object.
+		def getHistoric(playback_id)
+			return Historic.new(self, playback_id)
+		end
+
+		# Get a list of Historics queries in your account.
+		#=== Parameters
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of Historics queries in your account.
+		#* +historics+ - An array of Hashes where each Hash is a Historics query.
+		def listHistorics(page = 1, per_page = 20)
+			return Historic::list(self, page, per_page)
+		end
+
+		#Create a new PushDefinition object for this user.
+		#=== Returns
+		#A PushDefinition object.
+		def createPushDefinition()
+			return PushDefinition.new(self)
+		end
+
+		#Get an existing PushSubscription from the API.
+		#=== Parameters
+		#* +subscription_id+ - The ID of the subscription to fetch.
+		#=== Returns
+		#A PushSubscription object.
+		def getPushSubscription(subscription_id)
+			return PushSubscription.get(self, subscription_id)
+		end
+
+		#Get the log entries for all push subscription or the given subscription.
+		#=== Parameters
+		#* +subscription_id+ - Optional subscription ID.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of matching log entries.
+		#* +log_entries+ - An array of Hashes where each Hash is a log entry.
+		def getPushSubscriptionLog(subscription_id = false)
+			if subscription_id
+				return getPushSubscription(subscription_id).getLog()
+			else
+				return PushSubscription.getLogs(self)
+			end
+		end
+
+		#Get a page of Push subscriptions in the given user's account, where each
+		#page contains up to per_page items. Results will be ordered according to
+		#the supplied ordering parameters.
+		#=== Parameters
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#* +order_by+ - The field by which to order the results.
+		#* +order_dir+ - Ascending or descending.
+		#* +include_finished+ - True to include subscriptions against finished Historics queries.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of matching Push subscriptions in your account.
+		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+		def listPushSubscriptions(page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+			return PushSubscription.list(self, page, per_page, order_by, order_dir, include_finished)
+		end
+
+		#Get a page of Push subscriptions in the given user's account, where each
+		#page contains up to per_page items. Results will be ordered according to
+		#the supplied ordering parameters.
+		#=== Parameters
+		#* +hash+ - The stream hash.
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#* +order_by+ - The field by which to order the results.
+		#* +order_dir+ - Ascending or descending.
+		#* +include_finished+ - True to include subscriptions against finished Historics queries.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of matching Push subscriptions in your account.
+		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+		def listPushSubscriptionsToStreamHash(hash, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+			return PushSubscription.listByStreamHash(self, hash, page, per_page, order_by, order_dir)
+		end
+
+		#Get a page of Push subscriptions in the given user's account, where each
+		#page contains up to per_page items. Results will be ordered according to
+		#the supplied ordering parameters.
+		#=== Parameters
+		#* +hash+ - The stream hash.
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#* +order_by+ - The field by which to order the results.
+		#* +order_dir+ - Ascending or descending.
+		#* +include_finished+ - True to include subscriptions against finished Historics queries.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of matching Push subscriptions in your account.
+		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+		def listPushSubscriptionsToPlaybackId(playback_id, page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC, include_finished = false)
+			return PushSubscription.listByPlaybackId(self, playback_id, page, per_page, order_by, order_dir)
+		end
+
+		#Returns a StreamConsumer-derived object for the given hash, for the
+		#given type.
+		#=== Parameters
+		#* +type+ - The consumer type for which to construct a consumer.
+		#* +hash+ - The hash to be consumed.
+		#=== Returns
+		#A StreamConsumer-derived object.
 		def getConsumer(type = nil, hash = nil, on_interaction = nil, on_stopped = nil)
 			StreamConsumer.factory(self, type, Definition.new(self, nil, hash))
 		end
 
-		# Returns the account balance information for this user.
+		#Returns the account balance information for this user.
+		#=== Returns
+		#A Hash containing the balance information.
 		def getBalance
-			callAPI('balance')['balance']
+			return callAPI('balance')['balance']
 		end
 
-		# Returns the usage data for this user. If a hash is provided then a more
-		# detailed breakdown using interaction types is retrieved and returned.
-		# === Parameters
-		#
-		# * +period+ - An optional period for which to fetch data ('hour' or 'day')
+		#Returns the usage data for this user. If a hash is provided then a more
+		#detailed breakdown using interaction types is retrieved and returned.
+		#=== Parameters
+		#* +period+ - An optional period for which to fetch data ('hour' or 'day')
+		#=== Returns
+		#A Hash containing the usage information.
 		def getUsage(period = 'hour')
-			if period != 'hour' and period != 'day'
-				raise EInvalidData, 'Period must be hour or day'
-			end
-
 			params = { 'period' => period }
 
-			callAPI('usage', params)
+			return callAPI('usage', params)
 		end
 
-		# Returns the user agent this library should use for all API calls.
+		#Returns the user agent this library should use for all API calls.
+		#=== Returns
+		#The user agent string.
 		def getUserAgent()
-			USER_AGENT
+			return USER_AGENT
 		end
 
-		# Sets the ApiClient object to use to access the API
+		#Sets the ApiClient object to use to access the API
+		#=== Parameters
+		#* +client+ - The API client object to be used.
 		def setApiClient(client)
 			@api_client = client
 		end
 
-		# Sets whether to use SSL for API and stream communication
+		#Sets whether to use SSL for API and stream communication.
+		#=== Parameters
+		#* +use_ssl+ - Pass true to use SSL.
 		def enableSSL(use_ssl = true)
 			@use_ssl = use_ssl
 		end
 
-		# Make a call to a DataSift API endpoint.
-		# === Parameters
-		#
-		# * +endpoint+ - The endpoint of the API call.
-		# * +params+ - The parameters to be passed along with the request.
+		#Make a call to a DataSift API endpoint.
+		#=== Parameters
+		#* +endpoint+ - The endpoint of the API call.
+		#* +params+ - A Hash of parameters to be passed along with the request.
+		#=== Returns
+		#A Hash containing the response data.
 		def callAPI(endpoint, params = {})
 			if !@api_client
 				@api_client = ApiClient.new()
@@ -119,6 +245,8 @@ module DataSift
 
 			case res['response_code']
 			when 200
+			when 201
+			when 204
 				# Do nothing
 			when 401
 				# Authentication failure
@@ -127,12 +255,12 @@ module DataSift
 				# Check the rate limit
 				raise RateLimitExceededError, retval['comment'] if @rate_limit_remaining == 0
 				# Rate limit is ok, raise a generic exception
-				raise APIError.new(403), retval.has_key?('error') ? retval['error'] : 'Unknown error'
+				raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
 			else
-				raise APIError.new(res['http_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
+				raise APIError.new(res['response_code']), retval.has_key?('error') ? retval['error'] : 'Unknown error'
 			end
 
-			retval
+			return retval
 		end
 	end
 end