jirarest2 0.0.3

data/lib/config.rb

@@ -0,0 +1,55 @@
+# Module to handle configuration files
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+=begin
+ Module to handle configuration files
+=end
+module Config
+=begin
+ Inspired by http://www.erickcantwell.com/2011/01/simple-configuration-file-reading-with-ruby/
+ reads a config-file and returns a hash
+=end
+  def self.read_configfile(config_file)
+    config_file = File.expand_path(config_file)
+
+    unless File.exists?(config_file) then
+      raise "Unable to find config file"
+    end
+    
+    regexp = Regexp.new(/\s+|"|\[|\]/)
+    
+    temp = Array.new
+    vars = Hash.new
+    
+    IO.foreach(config_file) { |line|
+      if line.match(/^\s*#/) #  don't care about lines starting with an # (even after whitespace)
+        next
+      elsif line.match(/^\s*$/) # no text, no content
+        next
+      else
+# Right now I don't know what to use scan for. It will escape " nice enough. But once that is excaped the regexp doesn't work any longer.
+#        temp[0],temp[1] = line.to_s.scan(/^.*$/).to_s.split("=")
+        temp[0],temp[1] = line.to_s.split("=")
+        temp.collect! { |val|
+          val.gsub(regexp, "")
+        }
+        vars[temp[0]] = temp[1]
+      end
+    }
+    return vars
+  end
+end

data/lib/connect.rb

@@ -0,0 +1,99 @@
+# class to handle connections
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+
+require 'net/http'
+require 'exceptions'
+require 'jirarest2/result'
+require "pp"
+
+
+=begin
+ An Connect object encasulates the connection to jira via REST. It takes an Credentials object and returns a Jirarest2::Result object or an exception if something went wrong.
+=end
+class Connect
+  
+=begin
+ Create an instance of Connect. It needs an Credentials object to be created.
+=end
+  def initialize(credentials)
+    @pass = credentials.password
+    @user = credentials.username
+    @CONNECTURL = credentials.connecturl
+  end
+
+  
+=begin
+ Execute the request
+ * operation = one of Get, Post, Delete, Put
+ * uritail = the last part of the REST URI
+ * data = data to be sent.
+=end
+  def execute(operation,uritail,data)
+    uri = nil
+    uri = URI(@CONNECTURL+uritail)
+    
+    if data != "" then
+      if operation != "Post" then # POST carries the payload in the body that's why we have to wait
+        uri.query = URI.encode_www_form(data)
+      end
+    end
+    
+    req = nil
+    req = Net::HTTP::const_get(operation).new(uri.request_uri) # "Classes Are Just Obejects, Too" (Design Patterns in Ruby, Russ Olsen, Addison Wessley)
+    req.basic_auth @user, @pass
+    req["Content-Type"] = "application/json;charset=UTF-8"
+
+    if data != "" then
+      if operation == "Post" then # POST carries the payload in the body
+        @payload = data.to_json
+        req.body = @payload
+      end
+    end
+    
+    # Ask the server
+    result = Net::HTTP.start(uri.host, uri.port) {|http|
+      http.request(req)
+    }
+    # deal with output
+    case result
+    when Net::HTTPUnauthorized #No login-credentials oder wrong ones.
+      raise Jirarest2::AuthentificationError, result.body
+    when Net::HTTPForbidden #Captcha-Time
+      #      pp res.get_fields("x-authentication-denied-reason")
+      # Result: ["CAPTCHA_CHALLENGE; login-url=http://localhost:8080/login.jsp"]
+      result.get_fields("x-authentication-denied-reason")[0] =~ /.*login-url=(.*)/
+      raise Jirarest2::AuthentificationCaptchaError, $1
+    end
+    
+    return Jirarest2::Result.new(result)
+  end # execute
+
+
+end # class
+
+=begin
+
+
+# Add a Key-Value for every search parameter you'd usually have.
+query={"jql"=>"project = MFTP", "startAt"=>0, "maxResults"=>4 }
+#pp query
+# Here we query all those that match our parameter.
+#result = get_response("search",query) 
+#pp result
+
+=end

data/lib/credentials.rb

@@ -0,0 +1,62 @@
+# class to get the credentials together
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+
+require "uri"
+
+=begin
+ A Credentials object contains the data required to connect to a JIRA(tm) instance.
+=end
+class Credentials
+
+  # username to use
+  attr_accessor :username
+  # password for the connection
+  attr_accessor :password
+  # url to connect to the JIRA(tm) instance
+  attr_reader :connecturl
+
+=begin
+  Create an instance of Credentials. 
+  Requires username, password and the url for the JIRA(tm) instance. (The URL should stop after the port. There is no guarantee it would work if there is any path component given.) 
+=end
+  def initialize(url,username,password)
+    @username = username
+    @password = password
+    uri = URI(url)
+    if uri.instance_of?(URI::HTTP) || uri.instance_of?(URI::HTTPS) then
+      @connecturl = url
+    else
+      raise Jirarest2::NotAnURLError
+    end
+  end
+
+=begin
+ Setter for the URL.
+
+ Throws an Jirarest2::NotAnURLError if the given String is not an URI.
+=end  
+  def connecturl=(url)
+    uri = URI(url)
+    if uri.instance_of?(URI::HTTP) || uri.instance_of?(URI::HTTPS) then
+      @connecturl = url
+    else
+      raise Jirarest2::NotAnURLError
+    end
+  end
+
+end

data/lib/exceptions.rb

@@ -0,0 +1,47 @@
+# module to handle all the exceptions in their own namespace
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+=begin
+ Keep all the Exceptions in their own module
+=end
+module Jirarest2
+  ## connections.rb
+
+  # Authentification failed 
+  class AuthentificationError < StandardError ; end
+  # Authentification failed and JIRA(tm) requires a login with captcha to continue
+  class AuthentificationCaptchaError < StandardError ; end
+
+  ## credentials.rb
+
+  # String given as an URI isn't one
+  class NotAnURLError < ArgumentError ; end
+
+  ## issue.rb
+
+  # Project does not exist in the given JIRA(tm) instance
+  class  WrongProjectException < ArgumentError; end
+  # Issue type does not exist in the given project
+  class WrongIssuetypeException < ArgumentError; end
+  # There is no field with this name for the given issue type
+  class WrongFieldnameException < ArgumentError; end
+  # value is not allowed for this type of fields
+  class ValueNotAllowedException < ArgumentError; end
+  # A field that is defined as "required" has not been given a value
+  class RequiredFieldNotSetException < ArgumentError; end
+
+end

data/lib/issue.rb

@@ -0,0 +1,266 @@
+# class to handle new issues (building them up, changing fields, persistence)
+#    Copyright (C) 2012 Cyril Bitterich
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+# TODO always recreating Connection is not really DRY - Find a way to fix it.
+
+=begin
+ An Issue object contains all the data of an issue
+=end
+class Issue
+  
+  require "connect"
+  
+  # issue type of the issue 
+  attr_reader :issuetype
+  # project the issue belongs to
+  attr_reader :project
+  # The issue numer if we got it somehow
+  attr_reader :issuekey
+  
+=begin
+  New initialize method we take the project and the type we want to use and take login info that might exist just right with us
+  project Name of the project this issue is to live in
+=end
+  def initialize (project,type,credentials)
+    connection = Connect.new(credentials)
+    query = {:projectKeys => project, :issuetypeNames => type, :expand => "projects.issuetypes.fields" }
+    answer = connection.execute("Get","issue/createmeta/",query)
+    jhash = answer.result
+    parse_json(jhash)
+    raise Jirarest2::WrongProjectException, project if @project == ""
+    raise Jirarest2::WrongIssuetypeException, type if @issuetype == ""
+  end
+
+=begin
+ It needs the hashed version of the json-snippet jira returns
+ It produces an instance-variable @issuefields that can be 
+=end
+  def parse_json (jhash)
+    @issuefields = Hash.new
+    @project = ""
+    @issuetype = ""
+    jhash["projects"].each { |value|
+      @project = value["key"]
+      value["issuetypes"].each { |value|
+        @issuetype = value["name"]
+        value["fields"].delete("project") #The project key is duplicate and will make us live harder afterwards. It is marked as required but nothing happens if this key is not set.
+        value["fields"].each { |key,value|
+          fields = Hash.new
+          fields["id"] = key
+          if value["name"] then
+            name = value["name"]
+          else
+            name = key
+          end
+          # If the allowed reponses are limited we want to know them.
+          if value["allowedValues"] then
+            # With custom fields the identifier is "value" with the built in ones it's "name"
+            identifier = "name"
+            if value["schema"]["custom"] then
+              identifier = "value"
+            end
+            allowedValues = Array.new
+            value["allowedValues"].each { |value|
+              allowedValues << value[identifier]
+            }
+            fields["allowedValuesIdentifier"] = identifier
+            fields["allowedValues"] = allowedValues
+          end
+          fields["required"] = value["required"] 
+          fields["type"] = value["schema"]["type"]
+          @issuefields[name] = fields if name != "Issue Type" # "Issue Type" is not really a required field as we have to assign it at another place anyway
+        }
+      }
+    }
+  end
+  
+=begin
+ Return the type of a field
+=end
+  def fieldtype(field)
+    # If the fieldname is wrong we want to tell this and stop execution (or maybe let the caller fix it)
+    if @issuefields[field].nil? then
+      raise Jirarest2::WrongFieldnameException, field
+    else
+      return @issuefields[field]["type"]
+    end
+  end
+  
+=begin
+ Return all the fields that are required for this issuetype
+=end
+  def get_requireds
+    names = Array.new
+    @issuefields.each {|key,value|
+      if value["required"] then
+        names << key
+      end
+    }
+    return names
+  end
+
+=begin
+ Return all the names of the fields
+=end
+  def get_fieldnames
+    names = Array.new
+    @issuefields.each {|key,value|
+        names << key
+    }
+    return names
+  end
+
+=begin
+ return the id of a field name
+=end
+  protected
+  def get_id(name)
+    return @issuefields["name"]["id"]
+  end
+
+=begin
+ return a hash that can be sent to jira
+Lets create a new issue
+query=
+{"fields"=>
+  { "project"=>{"key"=>"MFTP"}, 
+    "environment"=>"REST ye merry gentlemen.", 
+    "My own text"=>"Creating of an issue using project keys and issue type names using the REST API",
+    "issuetype"=> {"name"=>"My own type"}
+  }
+}
+=end
+  public
+  def jirahash
+    h = Hash.new
+    issuetype = {"issuetype" => {"name" => @issuetype}}
+    project = {"key" => @project}
+    fields = Hash.new
+    fields["project"] = project
+    # here we need to enter the relevant fields and their values
+    @issuefields.each { |key,value|
+      if key !=  "project" then
+        id = value["id"]
+        if ! value["value"].nil? then
+          fields[id] = value["value"]
+        end
+      end
+    }
+    fields = fields.merge!(issuetype)
+    h = {"fields" => fields}
+    return h
+  end
+
+=begin
+ checks if the value is allowed for this field
+=end
+  protected
+  def value_allowed?(key,value)
+    if @issuefields[key]["allowedValues"].include?(value) 
+      return true
+    else
+      raise Jirarest2::ValueNotAllowedException, @issuefields[key]["allowedValues"]
+      puts "Value #{value} not allowed for field #{key}."
+    end
+  end
+
+=begin
+ Special setter for fields that have a limited numer of allowed values.
+
+ This setter might be included in set_field at a later date.
+=end
+  def set_allowed_value(key,value)
+    if @issuefields[key]["type"] == "array" && value.instance_of?(Array)  then
+      array = Array.new
+      value.each {|item|
+        if value_allowed?(key,item) then
+          array << {@issuefields[key]["allowedValuesIdentifier"] => item}
+        end
+      }
+      @issuefields[key]["value"] = array
+    else
+      if value_allowed?(key,value) then
+        @issuefields[key]["value"] = {@issuefields[key]["allowedValuesIdentifier"] => value}
+      end
+    end
+  end
+
+=begin
+  Setter fuer die Felder des Issues
+  :key is the name of the field
+  :value is is the value the field should get , this is either a String or an Array (don't know if numbers work too)
+TODO We are not yet able to work with "Cascading Select" fields ( "custom": "com.atlassian.jira.plugin.system.customfieldtypes:cascadingselect")
+=end
+  public
+  def set_field(key, value)
+    if  @issuefields.include?(key) then
+      if @issuefields[key].include?("allowedValues") then
+        set_allowed_value(key,value)
+      else
+        @issuefields[key]["value"] = value
+      end
+    else
+      raise Jirarest2::WrongFieldnameException, key
+      puts "Unknown Field: #{key}"
+    end
+  end
+
+=begin
+  Get the value of a certain field
+=end
+  def get_field(field)
+    @issuefields[field]["value"]
+  end
+
+=begin
+ create a new ticket
+=end
+  def persist(credentials)
+    get_requireds.each { |fieldname| 
+      if @issuefields[fieldname]["value"].nil? then
+        raise Jirarest2::RequiredFieldNotSetException, fieldname
+      end
+    }
+    connection = Connect.new(credentials)
+    hash = jirahash
+    # TODO we changed the returning Value here - it's an Result object and no longer just the equivalent of Result.result
+    ret = connection.execute("Post","issue/",hash) 
+    if ret.code == "201" then # Ticket sucessfully created
+      @issuekey = ret.result["key"]
+    end
+    return ret
+  end
+
+
+=begin
+ Set the watchers for this Ticket
+ watchers has to be an Array
+=end
+  def add_watchers(credentials,watchers)
+    success = false # Return whether we were successful with the watchers
+    connection = Connect.new(credentials)
+    watch = Watcher.new(connection,@issuekey)
+    watchers.each { |person|
+      success = watch.add_watcher(person)
+    }
+    return success
+  end
+
+  
+end # class
+
+