Class: RestQuery

Inherits:
Object
  • Object
show all
Defined in:
lib/rally_rest_api/query.rb

Overview

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

If you have ruport installed, you may also call to_table on a QueryResult to convert the result to a Ruport::Data:Table

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type, args = {}, &block) ⇒ RestQuery

Returns a new instance of RestQuery.



89
90
91
92
93
94
95
96
 
# File 'lib/rally_rest_api/query.rb', line 89

def initialize(type, args = {}, &block)
  @type = type
  @query_string = "query=" << URI.escape(QueryBuilder.new("and", &block).to_q) if block_given?
  @query_string.gsub!("&", "%26")
  @args_for_paging = {}
  [:workspace, :project, :project_scope_down, :project_scope_up, :order, :fetch].each { |k| @args_for_paging[k] = args[k] if args.key?(k) }
  @query_params = process_args(args)
end

Instance Attribute Details

#type ⇒ Object (readonly)

Returns the value of attribute type.



87
88
89
 
# File 'lib/rally_rest_api/query.rb', line 87

def type
  @type
end

Class Method Details

.query(&block) ⇒ Object 



124
125
126
 
# File 'lib/rally_rest_api/query.rb', line 124

def self.query(&block)
  QueryBuilder.new("and", &block).to_q
end

Instance Method Details

#next_page(args) ⇒ Object 



115
116
117
118
 
# File 'lib/rally_rest_api/query.rb', line 115

def next_page(args)
  @query_params = process_args(args.merge(@args_for_paging))
  self
end

#process_args(args) ⇒ Object

:nodoc:



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/rally_rest_api/query.rb', line 98

def process_args(args) # :nodoc:
  return if args.nil?
  query_string = ""
  args.each do |k, v|
    case k
    when :order
	# this is a hack, we need a better way to express descending
	v = [v].flatten.map { |e| e.to_s.to_camel }.join(", ").gsub(", Desc", " desc")
    when :fetch
      raise "value for fetch must be either true or false" unless v.to_q == "true" || v.to_q == "false"         
    end
    key = de_underscore(k)
    query_string << "&#{key}=#{URI.escape(v.to_q)}"
  end
  query_string
end

#to_q ⇒ Object 



120
121
122
 
# File 'lib/rally_rest_api/query.rb', line 120

def to_q
  "#{@query_string}#{@query_params}"
end