rally_rest_api 0.5.5

data/CHANGELOG.txt

@@ -0,0 +1,4 @@
+2006-11-27  Bob Cotton  <bcotton@england.f4tech.com>
+
+	* lib/rally_rest_api/query.rb: Added docs.
+

data/Manifest.txt

@@ -0,0 +1,19 @@
+CHANGELOG.txt
+History.txt
+lib/rally_rest_api/query.rb
+lib/rally_rest_api/query_result.rb
+lib/rally_rest_api/rally_rest.rb
+lib/rally_rest_api.rb
+lib/rally_rest_api/rest_builder.rb
+lib/rally_rest_api/rest_object.rb
+lib/rally_rest_api/typedef.rb
+lib/rally_rest_api/version.rb
+Manifest.txt
+Rakefile
+README.txt
+setup.rb
+test/tc_query_result.rb
+test/tc_rest_api.rb
+test/tc_rest_object.rb
+test/tc_rest_query.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,111 @@
+rally-rest-api -- A Ruby-ized interface to Rally's REST webservice API
+
+==Introduction:
+Rally Software Development's on-demand agile software life-cycle management services offers webservices API's for its customers. The API comes in both SOAP and REST style interfaces. This library is for accessing the REST API using Ruby. For more information about Rally's webservice APIs see https://rally1.rallydev.com/slm/doc/webservice/index.jsp.
+
+This API provides full access to all CRUD operations and an rich interface to the query facility. An Enumerable interface is provided for the paginated query results.
+
+== Rationale (i.e. Why not SOAP?):
+Your subscription in Rally can be partitioned into several isolated "Workspaces", where the only thing shared between workspaces are your users. Any custom attributes you create will be specific to each workspace. When using the SOAP interface, the WSDL generated is specific to the workspace you are working in. Therefore the name-space (e.g. package in Java) will be different for each workspace you are working with.
+
+Because REST webservices do not have WSDL (the XML schema is available for each workspace), there is no per-workspace interface. Combined with the dynamic nature of this API, you don't need to code to different Ruby namespaces when you are working with multiple workspaces. You will however, need to be aware of the workspaces your objects are in when working with multiple workspaces.
+
+== Getting Started:
+RallyRestAPI is the entry point to the api. Each instance corresponds to one user logged into Rally. There are several options that may be passed to the constructor:
+    :username         => Your Rally login username.
+    :password         => Your Rally login password. Username and password will be remembered by this 
+                         instance of the API and all objects created and read by this instance.
+    :base_url         => The base url for the system you are talking to. Defaults to https://rally1.rallydev.com/slm/
+    :raise_on_warning => true|false or the exception class you would like raised. If true, RuntimeError will be raised.
+    :logger           => A logger to log to. There is interesting logging info for DEBUG and INFO
+
+== Rest Object:
+All rally resources referenced by the api are of type RestObject, there are no subclasses. In its initial form a RestObject is just a URL representing a resource. This URL is accessed using RestObject#ref. When more information is requested about the object, the API will read the content of that resource. This read is done lazily and transparently.
+
+Objects can reference other objects in Rally. When establishing these relationships using this API, they are done using RestObjects. For example, to associate a user story to a defect, you would use the 'requirement' association on defect to reference the User Story. Here 'defect' and 'user_story' already exist, and the variables contain RestObjects representing them:
+
+  defect.update(:requirement => user_story)
+
+== CRUD and Query:
+
+Given an instance of the RallyRestAPI:
+
+      rally = RallyRestAPI.new(:username => <username>,
+                               :password => <password>)
+
+=== Create: 
+
+RallyRestAPI#create(<rally artifact type>, <artifact attributes as a hash>) returns a RestObject:
+
+    defect = rally.create(:defect, :name => "Defect name")
+
+#create will also accept a block, and yield the newly created reference to the block
+
+    rally.create(:defect, :name => "Defect name") do |defect|
+      # do something with defect here
+    end
+
+The block form is useful for creating relationships between objects in a readable way. For example, to create a User Story (represented by the type HierarchicalRequirement) with a task:
+
+    rally.create(:hierarchical_requirement, :name => "User Story One", :iteration => iteration_one) do |user_story|
+      rally.create(:task, :name => "Task One", :work_product => user_story)
+    end
+
+The above example will create a UserStory, pass it to the block, then create a Task on that User Story using the task's 'WorkProduct' relationship.
+
+=== Read:
+As mentioned above, RestObject will lazy read themselves on demand. If you need to force a RestObject to re-read itself, call RestObject#refresh. 
+
+=== Update:
+There are two ways to update an object:
+
+    RallyRestAPI#update(<rest object>, <attributes>)
+    RestObject#update(<attributes>)
+
+which is to say, a RestObject can update itself
+
+    defect.update(:name => "new name")
+
+Or the rest api can update it:
+
+    rally.update(defect, :name => "new name")
+
+=== Delete:
+There are two ways to delete an object:
+
+    RallyRestAPI#delete(<rest object>)
+    RestObject#delete
+
+which is to say, a RestObject can delete itself
+
+    defect.delete
+
+Or the rest api can delete it:
+
+    rally.delete(defect)
+
+=== Query:
+RallyRestAPI#find is the interface to the query syntax of Rally's webservice APIs.  The query interface in Ruby provides full support for this query syntax including all the operators. A quick example:
+
+    query_result = rally.find(:defect) { equal :name, "Defect name" }
+
+In addition to the type, #find accepts other arguments as a hash:
+
+  :pagesize => <number> - The number of results per page. Max of 100
+  :start => <number> - The record number to start with. Assuming more then page size records.
+  :fetch => <boolean> - If this is set to true then entire objects will be returned inside the query result. If set to false (the default) then only object references will be returned.
+  :workspace - If not present, then the query will run in the user's default workspace. If present, this should be the RestObject containing the workspace the user wants to search in.
+  :project - If not set, or specified as "null" then the "parent project" in the given workspace is used. If set, this should be the RestObject containing the project. Furthermore, if set you may omit the workspace parameter because the workspace will be inherited from the project.
+  :project_scope_up - Default is true. In addition to the specified project, include projects above the specified one.
+  :project_scope_down - Default is true. In addition to the specified project, include child projects below the current one.
+
+The return from #find is always a QueryResult. The QueryResult provides an interface to the paginated query result.
+
+  #each will iterate all results on all pages.
+  #total_result_count is the number of results for the whole query.
+  #page_length is the number of elements in the current page of result. 
+  #results returns an Array for the current page of results. 
+
+Because of the paginated nature of the result list, deleting elements while using #each is undefined.
+
+See the rdoc for RestQuery for more query examples.

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'rally_rest_api', 'version')
+
+AUTHOR = "Bob Cotton"  # can also be an array of Authors
+EMAIL = "bob.cotton@ralldev.com"
+DESCRIPTION = "A ruby-ized interface to Rally's REST webservices API"
+GEM_NAME = "rally_rest_api" # what ppl will type to install your gem
+RUBYFORGE_PROJECT = "rally-rest-api" # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+RELEASE_TYPES = %w( gem ) # can use: gem, tar, zip
+
+
+NAME = "rally_rest_api"
+REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (RallyRestAPI::VERSION::STRING + (REV ? ".#{REV}" : ""))
+CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "rally_rest_api documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/tc_*.rb"]
+  p.clean_globs = CLEAN  #An array of file patterns to delete on clean.
+  p.extra_deps = ["builder"]
+
+  # == Optional
+  #p.changes        - A description of the release's latest changes.
+
+  #p.spec_extras    - A hash of extra values to set in the gemspec.
+end
+          

data/lib/rally_rest_api.rb

@@ -0,0 +1 @@
+Dir[File.join(File.dirname(__FILE__), 'rally_rest_api/**/*.rb')].sort.each { |lib| require lib }

data/lib/rally_rest_api/query.rb

@@ -0,0 +1,170 @@
+require 'uri'
+
+class String # :nodoc: all
+  def to_camel
+    self.split(/\./).map { |word| word.split(/_/).map { |word| word.capitalize }.join}.join('.')
+  end
+  
+  alias :to_q :to_s
+end
+
+class Symbol # :nodoc: all
+    def to_q
+      self.to_s.to_camel
+    end
+end
+
+# == Generate a query string for Rally's webservice query interface.
+# Arguments are:
+#  type - the type to query for
+#  args - arguments to the query. Supported values are
+#  :pagesize => <number> - The number of results per page. Max of 100
+#  :start => <number> - The record number to start with. Assuming more then page size records.
+#  :fetch => <boolean> - If this is set to true then entire objects will be returned inside the query result. If set to false (the default) then only object references will be returned.
+#  :workspace - If not present, then the query will run in the user's default workspace. If present, this should be the RestObject containing the workspace the user wants to search in.
+#  :project - If not set, or specified as "null" then the "parent project" in the given workspace is used. If set, this should be the RestObject containing the project. Furthermore, if set you may omit the workspace parameter because the workspace will be inherited from the project.
+#  :project_scope_up - Default is true. In addition to the specified project, include projects above the specified one.
+#  :project_scope_down - Default is true. In addition to the specified project, include child projects below the current one.
+#  &block - the query parameters
+#
+# === The query parameters block
+#
+# The query parameters block is a DSL the specifying the query parameters. Single attribute specifiers are
+# written in prefix notation in the form:
+#  <operator> <attribute symbol>, <value>
+# for example
+#  equal :name, "My Name"
+# Allowed operators and their corresponding generated query strings are:
+#    equal              => "="
+#    not_equal          => "!="
+#    contains           => "contains"
+#    greater_than       => ">"
+#    gt                 => ">"
+#    less_than          => "<"
+#    lt                 => "<"
+#    greater_than_equal => ">="
+#    gte                => ">="
+#    less_then_equal    => "<="
+#    lte                => "<="
+# 
+# == Boolean logic.
+#
+# By default, if more then one query parameter is specified in the block, then those parameters will be ANDed together.
+# For example, if the query parameter block contains the follow expression:
+#  equal :name, "My Name"
+#  greater_than :priority, "Fix Immediately"
+# these expressions will be ANDed together. You may specify explicit AND and OR operators using the 
+# _and_ and _or_ operators, which also accept parameter blocks. For example the above expression could also have 
+# been written:
+#  _and_ {
+#    equal :name, "My Name"
+#    greater_than :priority, "Fix Immediately"
+#  }
+# \_or_ works in the same fashion. _and_s and _or_s may be nested as needed. See the test cases for RestQuery for
+# more complex examples
+#
+class RestQuery
+  attr_reader :type
+
+  def initialize(type, *args, &block)
+    @type = type
+    @query_string = "query=" << URI.escape(QueryBuilder.new("and", &block).to_q) if block_given?
+    @query_params = process_args(args[0])
+  end
+
+  def process_args(args) # :nodoc"
+    return if args.nil?
+    query_string = ""
+    args.each do |key, value|
+      case key
+      when :order
+	# this is a hack, we need a better way to express descending
+	value = [value].flatten.map { |e| e.to_s.to_camel }.join(", ").gsub(", Desc", " desc")
+      end
+      query_string << "&#{key}=#{URI.escape(value.to_s)}" 
+    end
+    query_string
+  end
+
+  def next_page(args)
+    @query_params = process_args(args)
+    self
+  end
+
+  def to_q
+    "#{@query_string}#{@query_params}"
+  end
+
+  def self.query(&block)
+    QueryBuilder.new("and", &block).to_q
+  end
+end
+
+# Internal support for generating query string for the Rally Webservice.
+# See RestQuery for examples.
+class QueryBuilder # :nodoc: all
+  attr_reader :operator
+
+  # Define the operators on the query terms. I've include perl-like operators for 
+  # less_than and greater_then etc.
+  { 
+    :equal              => "=",
+    :not_equal          => "!=",
+    :contains           => "contains",
+    :greater_than       => ">",
+    :gt                 => ">",
+    :less_than          => "<",
+    :lt                 => "<",
+    :greater_than_equal => ">=",
+    :gte                => ">=",
+    :less_then_equal    => "<=",
+    :lte                => "<=",
+  }.each do |method, operator|
+    module_eval     %{def #{method}(lval, rval)
+                       rval = \"\\"\#{rval}\\"\" if rval =~ / /
+                       add(QueryString.new(lval, \"#{operator}\", rval), @operator)
+                      end}
+  end
+
+
+  def initialize(operator, &block)
+    @operator = operator
+    instance_eval(&block)
+  end
+
+  def _and_(&block)
+    add(QueryBuilder.new("and", &block), @operator)
+  end
+  
+  def _or_(&block)
+    add(QueryBuilder.new("or", &block), @operator)
+  end
+  
+  def add(new_value, op)
+    if value.empty?
+      value.push new_value
+    else  
+      value.push QueryString.new(value.pop, op, new_value)  
+    end
+    self
+  end
+  
+  def value
+    @value ||= []
+  end
+
+  def to_q
+    value[0].to_q
+  end
+
+end
+
+class QueryString # :nodoc: all
+  def initialize(lhs, op, rhs)
+    @lhs, @op, @rhs = lhs, op, rhs
+  end
+
+  def to_q
+    "(#{@lhs.to_q} #{@op.to_q} #{@rhs.to_q})"
+  end
+end

data/lib/rally_rest_api/query_result.rb

@@ -0,0 +1,73 @@
+require 'rally_rest_api/rest_object'
+
+# == An interface to the paged query result 
+#
+# QueryResult is a wrapper around the xml returned from a webservice
+# query operation. A query could result in a large number of hits
+# being returned, therefore the query result is paged into page_size
+# chunks (20 by default). QueryResult will seamlessly deal with the
+# paging when using the #each iterator.
+#
+# === Example
+#  rally = RallyRestAPI.new(...)
+#  results = rally.find(:defect) { equal :name, "My Defects" }
+#  results.each do |defect|
+#    defect.update(:state => "Closed")
+#  end
+#
+# 
+class QueryResult < RestObject
+  attr_reader :total_result_count
+  attr_reader :page_size
+  attr_reader :start_index
+
+  def initialize(query, rally_rest, document_content)
+    super(rally_rest, document_content)
+    elements[:results] = case self.results
+      when Array : self.results.flatten
+      when Hash : self.results.values.flatten
+      when nil : []
+    end
+                           
+    @query = query
+
+    @total_result_count = elements[:total_result_count].to_i
+    @page_size = elements[:page_size].to_i
+    @start_index = elements[:start_index].to_i
+  end
+
+  # fetch the next page of results. Uses the original query to generate the query string.
+  def next_page
+    @rally_rest.query(@query.next_page(:start => self.start_index + self.page_size,
+				       :pagesize => self.page_size))
+  end
+
+  # Iteration all pages of the result
+  def each
+    current_result = self
+    while current_result.more_pages?
+      current_result.elements[:results].each do |result|
+	# The collection of refs we are holding onto could grow without bounds, so dup
+	# the ref
+	yield result.dup
+      end
+      current_result = current_result.next_page
+    end
+  end
+
+  # return the first element. Useful for queries that return only one result
+  def first
+    results.first
+  end
+
+  # The length of the current page of results
+  def page_length
+    return 0 if self.elements[:results].nil?
+    self.elements[:results].length
+  end
+
+  # Are there more pages?
+  def more_pages?
+    (self.start_index + self.page_length) < self.total_result_count
+  end
+end

data/lib/rally_rest_api/rally_rest.rb

@@ -0,0 +1,100 @@
+require 'net/http'
+require 'uri'
+require 'rexml/document'
+require 'ostruct'
+
+require 'rally_rest_api/rest_builder'
+require 'rally_rest_api/query'
+require 'rally_rest_api/rest_object'
+require 'rally_rest_api/query_result'
+
+#
+# RallyRestAPI - A Ruby-ized interface to Rally's REST webservice API
+#
+class RallyRestAPI
+  include RestBuilder
+ 
+  attr_reader :username, :password, :base_url, :raise_on_warning, :logger
+
+  ALLOWED_TYPES = %w[subscription workspace project iteration release defect defect_suite test_case
+                     feature supplemental_requirement use_case story actor card
+                     program task hierarchical_requirement test_case_result test_case_step]
+  
+  # new - Create an instance of RallyRestAPI. Each instance corresponds to one named user.
+  #
+  # options (as a Hash):
+  # * username  - The Rally username
+  # * password  - The password for the named user
+  # * base_url  - The base url of the system. Defaults to https://rally1.rallydev.com/slm
+  # * raise_on_warn - true|false|Exception Class. If you want exceptions raised on warnings. Default is false. if 'true' RuntimeException will be raised. If ExceptionClass, then an instance of that will be raised.
+  # * logger    - a Logger to log to.
+  #
+  def initialize(options = {:base_url => "https://rally1.rallydev.com/slm"})
+    parse_options options
+  end
+
+  def parse_options(options)
+    @username = options[:username]
+    @password = options[:password]
+    @base_url = options[:base_url]
+    @raise_on_warning = options[:raise_on_warning]
+    @logger = options[:logger]
+  end
+
+  # return an instance of User, for the currently logged in user. 
+  def user
+    RestObject.new(self, read_rest("#{@base_url}/webservice/1.0/user", @username, @password))
+  end
+  alias :start :user # :nodoc:
+
+  # This is deprecated, use create instead
+  def method_missing(type, args, &block) # :nodoc:
+#    raise "'#{type}' is not a supported type. Supported types are: #{ALLOWED_TYPES.inspect}" unless ALLOWED_TYPES.include?(type.to_s)
+    create_rest(type, args, @username, @password)
+  end
+
+  # Create an object.
+  #  type   - The type to create, as a symbol (e.g. :test_case)
+  #  values - The attributes of the new object.
+  #
+  # The created instance will be passed to the block
+  #
+  # returns the created object as a RestObject.
+  def create(type, values) # :yields: new_object
+#    raise "'#{type}' is not a supported type. Supported types are: #{ALLOWED_TYPES.inspect}" unless ALLOWED_TYPES.include?(type.to_s)
+    object = create_rest(type, values, @username, @password)
+    yield object if block_given?
+    object
+  end
+
+  # Query Rally for a collection of objects
+  # Example :
+  #   rally.find(:artifact, :page_size => 20, :start_index => 20) { equal :name, "name" }
+  # See RestQuery for more info.
+  def find(type, *args, &query)
+    # pass the args to RestQuery, make it generate the string and handle generating the query for the 
+    # next page etc.
+    query = RestQuery.new(type, args, &query)
+    query(query)
+  end
+
+  # update - update an object
+  def update(rest_object, attributes)
+    rest_object.update(attributes)
+  end
+
+  # delete an object
+  def delete(rest_object)
+    rest_object.delete
+  end
+  
+  private
+  def query(query) 
+    query_url = "#{@base_url}/webservice/1.0/#{query.type.to_s.to_camel}?" << query.to_q
+    xml = read_rest(query_url, @username, @password)
+    QueryResult.new(query, self, xml)
+  end
+
+end
+
+