leantesting 1.0.0

data/lib/BaseClass/Entity.rb

@@ -0,0 +1,33 @@
+#
+# Represents a single Entity. All remote responses are decoded and parsed into one or more Entities.
+#
+
+class Entity
+	attr_accessor :data
+
+	@origin	= nil # Reference to originating Client instance
+	@data	= nil # Internal entity object data
+
+	#
+	# Constructs an Entity instance
+	#
+	# Arguments:
+	#	origin Client -- Original client instance reference
+	#	data   Hash       -- Data to be contained in the new Entity. Must be non-empty.
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided data param is not a hash.
+	#	SDKInvalidArgException if provided data param is empty. Entities cannot be empty.
+	#
+	def initialize(origin, data)
+		if !data.is_a? Hash
+			raise SDKInvalidArgException, '`data` must be a hash'
+		elsif data.length.zero?
+			raise SDKInvalidArgException, '`data` must be non-empty'
+		end
+
+		@origin	= origin
+		@data	= data
+	end
+
+end

data/lib/BaseClass/EntityHandler.rb

@@ -0,0 +1,183 @@
+#
+# An EntityHandler is the equivalent of a method centralizer for a corresponding endpoint (such as /v1/entities).
+#
+# Functional naming conventions and equivalents:
+#	create(fields)      <=>  `Create a new Entity`
+#	all(fields)         <=>  `List all Entities`
+#	find(id)            <=>  `Retrieve an existing Entity`
+#	delete(id)          <=>  `Delete an Entity`
+#	update(id, fields)  <=>  `Update an Entity`
+#
+class EntityHandler
+
+	#
+	# Constructs an EntityHandler instance
+	#
+	# Keyword arguments:
+	#	origin Client -- Originating client reference
+	#
+	def initialize(origin)
+		@origin = origin # Reference to originating Client instance
+	end
+
+	#
+	# Function definition for creating a new entity. Base function checks for invalid parameters.
+	#
+	# Keyword arguments:
+	#	fields Hash -- Non-empty hash consisting of entity data to send for adding
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided fields param is not a hash.
+	#	SDKInvalidArgException if provided fields param is empty.
+	#
+	def create(fields)
+		if !fields.is_a? Hash
+			raise SDKInvalidArgException, '`fields` must be a hash'
+		elsif fields.length.zero?
+			raise SDKInvalidArgException, '`fields` must be non-empty'
+		end
+	end
+
+	#
+	# Function definition for listing all entities. Base function checks for invalid parameters.
+	#
+	# Keyword arguments:
+	#	filters Hash -- (optional) Filters to apply to restrict listing. Currently supported: limit, page
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided filters param is not a hash.
+	#	SDKInvalidArgException if invalid filter value found in filters hash.
+	#
+	def all(filters = nil)
+		if !filters
+			filters = {}
+		end
+
+		if !filters.is_a? Hash
+			raise SDKInvalidArgException, '`filters` must be a hash'
+		else
+			filters.each do |k,|
+				if !['include', 'limit', 'page'].include? k
+					raise SDKInvalidArgException, 'unsupported ' + k + ' for `filters`'
+				end
+			end
+		end
+
+	end
+
+	#
+	# Function definition for retrieving an existing entity. Base function checks for invalid parameters.
+	#
+	# Keyword arguments:
+	#	id Fixnum -- ID field to look for in the entity collection
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided id param is not an integer.
+	#
+	def find(id)
+		if !id.is_a? Fixnum
+			raise SDKInvalidArgException, '`id` must be of type Fixnum'
+		end
+	end
+
+	#
+	# Function definition for deleting an existing entity. Base function checks for invalid parameters.
+	#
+	# Keyword arguments:
+	#	id Fixnum -- ID field of entity to delete in the entity collection
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided id param is not an integer.
+	#
+	def delete(id)
+		if !id.is_a? Fixnum
+			raise SDKInvalidArgException, '`id` must be of type Fixnum'
+		end
+	end
+
+	#
+	# Function definition for updating an existing entity. Base function checks for invalid parameters.
+	#
+	# Keyword arguments:
+	#	id     Fixnum -- ID field of entity to update in the entity collection
+	#	fields Hash   -- Non-empty dictionary consisting of entity data to send for update
+	#
+	# Exceptions:
+	#	SDKInvalidArgException if provided id param is not an integer.
+	#	SDKInvalidArgException if provided fields param is not a hash.
+	#	SDKInvalidArgException if provided fields param is empty.
+	#
+	def update(id, fields)
+		if !id.is_a? Fixnum
+			raise SDKInvalidArgException, '`id` must be of type Fixnum'
+		elsif !fields.is_a? Hash
+			raise SDKInvalidArgException, '`fields` must be a hash'
+		elsif fields.length.zero?
+			raise SDKInvalidArgException, '`fields` must be non-empty'
+		end
+	end
+
+	private
+
+	#
+	# Helper function that enforces a structure based on a supported table:
+	#	- Forces use of REQUIRED fields
+	#	- Detects duplicate fields
+	#	- Detects unsupported fields
+	#
+	# Keyword arguments:
+	#	obj      Hash -- Hash to be enforced
+	#	supports Hash -- Support table consisting of REQUIRED and OPTIONAL keys to be used in enforcing
+	#
+	# Exceptions:
+	#	SDKUnsupportedRequestException if unsupported fields are found
+	#	SDKIncompleteRequestException  if any required field is missing
+	#	SDKDuplicateRequestException   if any duplicate field is found
+	#
+	def enforce(obj, supports)
+		sall = []				# All supported keys
+		sreq = []				# Mandatory supported keys
+
+		socc = supports.clone	# Key use occurances
+
+		unsup = []				# Unsupported key list
+		dupl  = []				# Duplicate key list
+		mreq  = []				# Missing required keys
+
+		supports.each do |sk, sv|
+			if sv == true
+				sreq.push(sk)
+			end
+
+			sall.push(sk)
+			socc[sk] = 0
+		end
+
+		obj.each do |k,|
+			if sall.include? k
+				socc[k] += 1
+			else
+				unsup.push(k)
+			end
+		end
+
+		socc.each do |ok, ov|
+			if ov > 1
+				dupl.push(ok)
+			elsif ov == 0 && sreq.include?(ok)
+				mreq.push(ok)
+			end
+		end
+
+		if unsup.length.nonzero?
+			raise SDKUnsupportedRequestException, unsup
+		elsif mreq.length.nonzero?
+			raise SDKIncompleteRequestException, mreq
+		elsif dupl.length.nonzero?
+			raise SDKDuplicateRequestException, dupl
+		end
+
+		true
+	end
+
+end

data/lib/BaseClass/EntityList.rb

@@ -0,0 +1,188 @@
+#
+# An EntityList is a list of Entity objects, obtained from compiling the results of an all() call.
+#
+class EntityList
+	attr_reader :collection
+
+	@origin     = nil # Reference to originating Client instance
+
+	@identifier = nil # Class definition identifier for the collection Entities
+	@collection = nil # Internal collection corresponding to current page
+
+	@request    = nil # APIRequest definition to use for collection generation
+	@filters    = nil # Filter list for generation (origins in Handler call)
+
+	@pagination = nil # Pagination object as per response (without links)
+
+	#
+	# Constructs an Entity List instance.
+	#
+	# Arguments:
+	#	origin     Client -- Original client instance reference
+	#	request    APIRequest -- An API Request definition given by the entity collection handler. This is used for any
+	#						subsequent collection regeneration, as any data updates are dependant on external requests.
+	#	identifier Class      -- class definition to use for dynamic class instancing within array collection
+	#	filters    Hash       -- original filters passed over from originating all() call
+	#
+	def initialize(origin, request, identifier, filters = nil)
+		if !filters
+			filters = {}
+		end
+
+		@origin     = origin
+		@request    = request
+		@identifier = identifier
+		@filters    = filters
+
+		generateCollectionData
+
+	end
+
+	#
+	# Sets iterator position to first page. Ignored if already on first page.
+	#
+	def first
+		if @pagination['current_page'] == 1
+			return false
+		end
+
+		@filters['page'] = 1
+		generateCollectionData
+	end
+
+	#
+	# Sets iterator position to previous page. Ignored if on first page.
+	#
+	def previous
+		if @pagination['current_page'] == 1
+			return false
+		end
+
+		@filters['page'] -=1
+		generateCollectionData
+	end
+
+	#
+	# Sets iterator position to next page. Ignored if on last page.
+	#
+	def next
+		if @pagination['current_page'] == @pagination['total_pages']
+			return false
+		end
+
+		if @filters.has_key? 'page'
+			@filters['page'] += 1
+		else
+			@filters['page'] = 2
+		end
+
+		generateCollectionData
+	end
+
+	#
+	# Sets iterator position to last page. Ignored if already on last page.
+	#
+	def last
+		if @pagination['current_page'] == @pagination['total_pages']
+			return false
+		end
+
+		@filters['page'] = @pagination['total_pages']
+		generateCollectionData
+	end
+
+	#
+	# Internal loop handler for emulating enumerable functionality
+	#
+	def each
+		first
+		begin
+			yield toArray
+		end while self.next
+	end
+
+	#
+	# Outputs total number of Entities inside multi-page collection
+	#
+	# Returns:
+	#	Fixnum -- Number of total Entities
+	#
+	def total
+		@pagination['total']
+	end
+
+	#
+	# Outputs total number of pages the multi-page collection has, regardful of limit/per_page
+	#
+	# Returns:
+	#	Fixnum -- Number of total pages
+	#
+	def totalPages
+		@pagination['total_pages']
+	end
+
+	#
+	# Outputs number of Entities in current collection page. Will always be same as limmit/per_page if not on last page.
+	#
+	# Returns:
+	#	Fixnum -- Number of Entities in page
+	#
+	def count
+		@pagination['count']
+	end
+
+	#
+	# Outputs internal collection in array format (converted from Entity objects)
+	#
+	# Returns:
+	#	Array -- array of elements converted into hashes
+	#
+	def toArray
+		@collection.map{ |entity| entity.data }
+	end
+
+	private
+
+	#
+	# (Re)generates internal collection data based on current iteration position.
+	#
+	# Regeneration is done every time position changes (i.e. every time repositioning functions are used).
+	#
+	# Exceptions:
+	#	SDKUnexpectedResponseException if no `meta` field is found
+	#	SDKUnexpectedResponseException if no `pagination` field is found in `meta field`
+	#	SDKUnexpectedResponseException if no collection set is found
+	#	SDKUnexpectedResponseException if multiple collection sets are found
+	#
+	def generateCollectionData
+		@collection = [] # Clear previous collection data on fresh regeneration
+		@pagination = {} # Clear previous pagination data on fresh regeneration
+
+		@request.updateOpts({'params' => @filters})
+		raw = @request.exec
+
+		if !raw.has_key? 'meta'
+			raise SDKUnexpectedResponseException, 'missing `meta` field'
+		elsif !raw['meta'].has_key? 'pagination'
+			raise SDKUnexpectedResponseException, '`meta` missing `pagination` field'
+		end
+
+		if raw['meta']['pagination'].has_key? 'links'
+			raw['meta']['pagination'].delete('links')	# Remove not needed links sub-data
+		end
+
+		@pagination = raw['meta']['pagination']			# Pass pagination data as per response meta key
+		raw.delete('meta')
+
+		if raw.length.zero?
+			raise SDKUnexpectedResponseException, 'collection object missing'
+		elsif raw.length > 1
+			cols = raw.map{ |k,| k }.join(', ')
+			raise SDKUnexpectedResponseException, 'expected one collection object, multiple received: ' + cols
+		end
+
+		classDef = @identifier # Definition to be used for dynamic Entity instancing
+		raw.values[0].each{ |entity| @collection.push(classDef.new(@origin, entity)) }
+	end
+
+end

data/lib/Entity/Bug/Bug.rb

@@ -0,0 +1,11 @@
+class Bug < Entity
+	attr_reader :comments, :attachments
+
+	def initialize(origin, data)
+		super
+
+		@comments		= BugCommentsHandler.new(origin, data['id'])
+		@attachments	= BugAttachmentsHandler.new(origin, data['id'])
+	end
+
+end

data/lib/Entity/Bug/BugAttachment.rb

@@ -0,0 +1,7 @@
+class BugAttachment < Entity
+
+	def initialize(origin, data)
+		super
+	end
+
+end

data/lib/Entity/Bug/BugComment.rb

@@ -0,0 +1,7 @@
+class BugComment < Entity
+
+	def initialize(origin, data)
+		super
+	end
+
+end

data/lib/Entity/Platform/PlatformBrowser.rb

@@ -0,0 +1,10 @@
+class PlatformBrowser < Entity
+	attr_reader :versions
+
+	def initialize(origin, data)
+		super
+
+		@versions = PlatformBrowserVersionsHandler.new(origin, data['id'])
+	end
+
+end

data/lib/Entity/Platform/PlatformBrowserVersion.rb

@@ -0,0 +1,7 @@
+class PlatformBrowserVersion < Entity
+
+	def initialize(origin, data)
+		super
+	end
+
+end