Class: JIRA::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/jira/client.rb

Overview

This class is the main access point for all JIRA::Resource instances.

The client must be initialized with an options hash containing configuration options. The available options are:

:site               => 'http://localhost:2990',
:context_path       => '/jira',
:signature_method   => 'RSA-SHA1',
:request_token_path => "/plugins/servlet/oauth/request-token",
:authorize_path     => "/plugins/servlet/oauth/authorize",
:access_token_path  => "/plugins/servlet/oauth/access-token",
:private_key        => nil,
:private_key_file   => "rsakey.pem",
:rest_base_path     => "/rest/api/2",
:consumer_key       => nil,
:consumer_secret    => nil,
:ssl_verify_mode    => OpenSSL::SSL::VERIFY_PEER,
:ssl_version        => nil,
:use_ssl            => true,
:username           => nil,
:password           => nil,
:auth_type          => :oauth,
:proxy_address      => nil,
:proxy_port         => nil,
:proxy_username     => nil,
:proxy_password     => nil,
:use_cookies        => nil,
:additional_cookies => nil,
:default_headers    => {},
:use_client_cert    => false,
:read_timeout       => nil,
:max_retries        => nil,
:http_debug         => false,
:shared_secret      => nil,
:cert_path          => nil,
:key_path           => nil,
:ssl_client_cert    => nil,
:ssl_client_key     => nil
:ca_file            => nil

See the JIRA::Base class methods for all of the available methods on these accessor objects.

Constant Summary collapse

DEFINED_OPTIONS = 
%i[
  site
  context_path
  signature_method
  request_token_path
  authorize_path
  access_token_path
  private_key
  private_key_file
  rest_base_path
  consumer_key
  consumer_secret
  ssl_verify_mode
  ssl_version
  use_ssl
  username
  password
  auth_type
  proxy_address
  proxy_port
  proxy_username
  proxy_password
  use_cookies
  additional_cookies
  default_headers
  use_client_cert
  read_timeout
  max_retries
  http_debug
  issuer
  base_url
  shared_secret
  cert_path
  key_path
  ssl_client_cert
  ssl_client_key
].freeze
DEFAULT_OPTIONS = 
{
  site: 'http://localhost:2990',
  context_path: '/jira',
  rest_base_path: '/rest/api/2',
  ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER,
  use_ssl: true,
  use_client_cert: false,
  auth_type: :oauth,
  http_debug: false,
  default_headers: {}
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ JIRA::Client

Creates a new JIRA::Client instance

Parameters:

  • options (Hash) (defaults to: {}) —

    The configuration options for the client

Options Hash (options):

  • :auth_type (Symbol) —

    The authentication type to use, :basic, :oauth, :oauth_2legged, or :cookie.

  • :site (String) —

    The base URL for the JIRA instance

  • :use_ssl (Boolean) —

    Whether to use HTTPS for requests

  • :ssl_verify_mode (Integer) —

    The SSL verification mode OpenSSL::SSL::VERIFY_PEER or OpenSSL::SSL::VERIFY_NONE

  • :default_headers (Hash) —

    Additional headers to send with each request

  • :cert_path (String) —

    The path to the SSL certificate file to verify the server with

  • :use_client_cert (String) —

    Whether to use a client certificate for authentication

  • :ssl_client_cert (String) —

    The client certificate to use

  • :ssl_client_key (String) —

    The client certificate key to use

  • :proxy_address (String) —

    The address of the proxy server to use

  • :proxy_port (Integer) —

    The port of the proxy server to use

  • :proxy_username (String) —

    The username for the proxy server

  • :proxy_password (String) —

    The password for the proxy server

Raises:

  • (ArgumentError) —

    If an unknown option is given



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/jira/client.rb', line 132

def initialize(options = {})
  options = DEFAULT_OPTIONS.merge(options)
  @options = options
  @options[:rest_base_path] = @options[:context_path] + @options[:rest_base_path]

  unknown_options = options.keys.reject { |o| DEFINED_OPTIONS.include?(o) }
  raise ArgumentError, "Unknown option(s) given: #{unknown_options}" unless unknown_options.empty?

  if options[:use_client_cert]
    if @options[:cert_path]
      @options[:ssl_client_cert] =
        OpenSSL::X509::Certificate.new(File.read(@options[:cert_path]))
    end
    @options[:ssl_client_key] = OpenSSL::PKey::RSA.new(File.read(@options[:key_path])) if @options[:key_path]

    unless @options[:ssl_client_cert]
      raise ArgumentError,
            'Options: :cert_path or :ssl_client_cert must be set when :use_client_cert is true'
    end
    unless @options[:ssl_client_key]
      raise ArgumentError,
            'Options: :key_path or :ssl_client_key must be set when :use_client_cert is true'
    end
  end

  case options[:auth_type]
  when :oauth, :oauth_2legged
    @request_client = OauthClient.new(@options)
    @consumer = @request_client.consumer
  when :jwt
    @request_client = JwtClient.new(@options)
  when :basic
    @request_client = HttpClient.new(@options)
  when :cookie
    if @options.key?(:use_cookies) && !@options[:use_cookies]
      raise ArgumentError,
            'Options: :use_cookies must be true for :cookie authorization type'
    end

    @options[:use_cookies] = true
    @request_client = HttpClient.new(@options)
    @request_client.make_cookie_auth_request
    @options.delete(:username)
    @options.delete(:password)
  else
    raise ArgumentError, 'Options: ":auth_type" must be ":oauth",":oauth_2legged", ":cookie" or ":basic"'
  end

  @http_debug = @options[:http_debug]

  @options.freeze
end

Instance Attribute Details

#consumer ⇒ Object

The OAuth::Consumer instance returned by the OauthClient

The authenticated client instance returned by the respective client type (Oauth, Basic)



57
58
59
 
# File 'lib/jira/client.rb', line 57

def consumer
  @consumer
end

#field_map_cache ⇒ Object

The OAuth::Consumer instance returned by the OauthClient

The authenticated client instance returned by the respective client type (Oauth, Basic)



57
58
59
 
# File 'lib/jira/client.rb', line 57

def field_map_cache
  @field_map_cache
end

#http_debug ⇒ Object

The OAuth::Consumer instance returned by the OauthClient

The authenticated client instance returned by the respective client type (Oauth, Basic)



57
58
59
 
# File 'lib/jira/client.rb', line 57

def http_debug
  @http_debug
end

#options ⇒ Object (readonly)

The configuration options for this client instance



60
61
62
 
# File 'lib/jira/client.rb', line 60

def options
  @options
end

#request_client ⇒ Object

The OAuth::Consumer instance returned by the OauthClient

The authenticated client instance returned by the respective client type (Oauth, Basic)



57
58
59
 
# File 'lib/jira/client.rb', line 57

def request_client
  @request_client
end

Instance Method Details

#Agile ⇒ Object 



301
302
303
 
# File 'lib/jira/client.rb', line 301

def Agile
  JIRA::Resource::AgileFactory.new(self)
end

#ApplicationLink ⇒ Object 



273
274
275
 
# File 'lib/jira/client.rb', line 273

def ApplicationLink
  JIRA::Resource::ApplicationLinkFactory.new(self)
end

#Attachment ⇒ Object

:nodoc:



229
230
231
 
# File 'lib/jira/client.rb', line 229

def Attachment # :nodoc:
  JIRA::Resource::AttachmentFactory.new(self)
end

#Board ⇒ Object 



249
250
251
 
# File 'lib/jira/client.rb', line 249

def Board
  JIRA::Resource::BoardFactory.new(self)
end

#BoardConfiguration ⇒ Object 



253
254
255
 
# File 'lib/jira/client.rb', line 253

def BoardConfiguration
  JIRA::Resource::BoardConfigurationFactory.new(self)
end

#Comment ⇒ Object

:nodoc:



225
226
227
 
# File 'lib/jira/client.rb', line 225

def Comment # :nodoc:
  JIRA::Resource::CommentFactory.new(self)
end

#Component ⇒ Object

:nodoc:



197
198
199
 
# File 'lib/jira/client.rb', line 197

def Component # :nodoc:
  JIRA::Resource::ComponentFactory.new(self)
end

#Createmeta ⇒ Object 



269
270
271
 
# File 'lib/jira/client.rb', line 269

def Createmeta
  JIRA::Resource::CreatemetaFactory.new(self)
end

#delete(path, headers = {}) ⇒ Net::HTTPResponse

Make an HTTP DELETE request

Parameters:

  • path (String) —

    The path to request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



312
313
314
 
# File 'lib/jira/client.rb', line 312

def delete(path, headers = {})
  request(:delete, path, nil, merge_default_headers(headers))
end

#Field ⇒ Object

:nodoc:



245
246
247
 
# File 'lib/jira/client.rb', line 245

def Field # :nodoc:
  JIRA::Resource::FieldFactory.new(self)
end

#Filter ⇒ Object

:nodoc:



193
194
195
 
# File 'lib/jira/client.rb', line 193

def Filter # :nodoc:
  JIRA::Resource::FilterFactory.new(self)
end

#get(path, headers = {}) ⇒ Net::HTTPResponse

Make an HTTP GET request

Parameters:

  • path (String) —

    The path to request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



321
322
323
 
# File 'lib/jira/client.rb', line 321

def get(path, headers = {})
  request(:get, path, nil, merge_default_headers(headers))
end

#head(path, headers = {}) ⇒ Net::HTTPResponse

Make an HTTP HEAD request

Parameters:

  • path (String) —

    The path to request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



330
331
332
 
# File 'lib/jira/client.rb', line 330

def head(path, headers = {})
  request(:head, path, nil, merge_default_headers(headers))
end

#Issue ⇒ Object

:nodoc:



189
190
191
 
# File 'lib/jira/client.rb', line 189

def Issue # :nodoc:
  JIRA::Resource::IssueFactory.new(self)
end

#Issuelink ⇒ Object 



285
286
287
 
# File 'lib/jira/client.rb', line 285

def Issuelink
  JIRA::Resource::IssuelinkFactory.new(self)
end

#Issuelinktype ⇒ Object 



289
290
291
 
# File 'lib/jira/client.rb', line 289

def Issuelinktype
  JIRA::Resource::IssuelinktypeFactory.new(self)
end

#IssuePickerSuggestions ⇒ Object 



293
294
295
 
# File 'lib/jira/client.rb', line 293

def IssuePickerSuggestions
  JIRA::Resource::IssuePickerSuggestionsFactory.new(self)
end

#Issuetype ⇒ Object

:nodoc:



205
206
207
 
# File 'lib/jira/client.rb', line 205

def Issuetype # :nodoc:
  JIRA::Resource::IssuetypeFactory.new(self)
end

#post(path, body = '', headers = {}) ⇒ Net::HTTPResponse

Make an HTTP POST request

Parameters:

  • path (String) —

    The path to request

  • body (String) (defaults to: '') —

    The body of the request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object



341
342
343
344
 
# File 'lib/jira/client.rb', line 341

def post(path, body = '', headers = {})
  headers = { 'Content-Type' => 'application/json' }.merge(headers)
  request(:post, path, body, merge_default_headers(headers))
end

#post_multipart(path, file, headers = {}) ⇒ Net::HTTPResponse

Make an HTTP POST request with a file upload

Parameters:

  • path (String) —

    The path to request

  • file (String) —

    The file to upload

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



352
353
354
355
 
# File 'lib/jira/client.rb', line 352

def post_multipart(path, file, headers = {})
  puts "post multipart: #{path} - [#{file}]" if @http_debug
  @request_client.request_multipart(path, file, merge_default_headers(headers))
end

#Priority ⇒ Object

:nodoc:



209
210
211
 
# File 'lib/jira/client.rb', line 209

def Priority # :nodoc:
  JIRA::Resource::PriorityFactory.new(self)
end

#Project ⇒ Object

:nodoc:



185
186
187
 
# File 'lib/jira/client.rb', line 185

def Project # :nodoc:
  JIRA::Resource::ProjectFactory.new(self)
end

#put(path, body = '', headers = {}) ⇒ Net::HTTPResponse

Make an HTTP PUT request

Parameters:

  • path (String) —

    The path to request

  • body (String) (defaults to: '') —

    The body of the request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



363
364
365
366
 
# File 'lib/jira/client.rb', line 363

def put(path, body = '', headers = {})
  headers = { 'Content-Type' => 'application/json' }.merge(headers)
  request(:put, path, body, merge_default_headers(headers))
end

#RapidView ⇒ Object 



257
258
259
 
# File 'lib/jira/client.rb', line 257

def RapidView
  JIRA::Resource::RapidViewFactory.new(self)
end

#Remotelink ⇒ Object 



297
298
299
 
# File 'lib/jira/client.rb', line 297

def Remotelink
  JIRA::Resource::RemotelinkFactory.new(self)
end

#request(http_method, path, body = '', headers = {}) ⇒ Net::HTTPResponse

Sends the specified HTTP request to the REST API through the appropriate method (oauth, basic).

Parameters:

  • http_method (Symbol) —

    The HTTP method to use

  • path (String) —

    The path to request

  • body (String) (defaults to: '') —

    The body of the request

  • headers (Hash) (defaults to: {}) —

    The headers to send with the request

Returns:

  • (Net::HTTPResponse) —

    The response object

Raises:



376
377
378
379
 
# File 'lib/jira/client.rb', line 376

def request(http_method, path, body = '', headers = {})
  puts "#{http_method}: #{path} - [#{body}]" if @http_debug
  @request_client.request(http_method, path, body, headers)
end

#Resolution ⇒ Object

:nodoc:



221
222
223
 
# File 'lib/jira/client.rb', line 221

def Resolution # :nodoc:
  JIRA::Resource::ResolutionFactory.new(self)
end

#ServerInfo ⇒ Object 



265
266
267
 
# File 'lib/jira/client.rb', line 265

def ServerInfo
  JIRA::Resource::ServerInfoFactory.new(self)
end

#Sprint ⇒ Object 



261
262
263
 
# File 'lib/jira/client.rb', line 261

def Sprint
  JIRA::Resource::SprintFactory.new(self)
end

#Status ⇒ Object

:nodoc:



213
214
215
 
# File 'lib/jira/client.rb', line 213

def Status # :nodoc:
  JIRA::Resource::StatusFactory.new(self)
end

#StatusCategory ⇒ Object

:nodoc:



217
218
219
 
# File 'lib/jira/client.rb', line 217

def StatusCategory # :nodoc:
  JIRA::Resource::StatusCategoryFactory.new(self)
end

#Transition ⇒ Object

:nodoc:



241
242
243
 
# File 'lib/jira/client.rb', line 241

def Transition # :nodoc:
  JIRA::Resource::TransitionFactory.new(self)
end

#User ⇒ Object

:nodoc:



201
202
203
 
# File 'lib/jira/client.rb', line 201

def User # :nodoc:
  JIRA::Resource::UserFactory.new(self)
end

#Version ⇒ Object

:nodoc:



237
238
239
 
# File 'lib/jira/client.rb', line 237

def Version # :nodoc:
  JIRA::Resource::VersionFactory.new(self)
end

#Watcher ⇒ Object 



277
278
279
 
# File 'lib/jira/client.rb', line 277

def Watcher
  JIRA::Resource::WatcherFactory.new(self)
end

#Webhook ⇒ Object 



281
282
283
 
# File 'lib/jira/client.rb', line 281

def Webhook
  JIRA::Resource::WebhookFactory.new(self)
end

#Worklog ⇒ Object

:nodoc:



233
234
235
 
# File 'lib/jira/client.rb', line 233

def Worklog # :nodoc:
  JIRA::Resource::WorklogFactory.new(self)
end