NAME
    JIRA::REST::Class - An OO Class module built atop "JIRA::REST" for
    dealing with JIRA issues and their data as objects.

VERSION
    version 0.02

SYNOPSIS
      use JIRA::REST::Class;

      my $jira = JIRA::REST::Class->new('https://jira.example.net',
                                        'myuser', 'mypass');

      # if your server uses self-signed SSL certificates
      $jira->SSL_verify_none;

      # allow the class to fetch the metadata for your project
      $jira->project('MYPROJECT');

      # get issue by key
      my ($issue) = $jira->issues('MYPROJECT-101');

      # get multiple issues by key
      my @issues = $jira->issues('MYPROJECT-101', 'MYPROJECT-102', 'MYPROJECT-103');

      # get multiple issues through search
      my @issues =
          $jira->issues({ jql => 'project = "'MYPROJECT" and status = "open"' });

      # get an iterator for a search
      my $search =
          $jira->iterator({ jql => 'project = "'MYPROJECT" and status = "open"' });

      if ( $search->issue_count ) {
          printf "Found %d open issues in MYPROJECT:\n", $search->issue_count;
          while ( my $issue = $search->next ) {
              printf "  Issue %s is open\n", $issue->key;
          }
      }
      else {
          print "No open issues in MYPROJECT.\n";
      }

DESCRIPTION
    An OO Class module built atop "JIRA::REST" for dealing with JIRA issues
    and their data as objects.

    This code is a work in progress, so it's bound to be incomplete. I add
    methods to it as I discover I need them. I also code for fields that
    might exist in my JIRA server's configuration but not in yours. It is my
    intent to make things more generic as I go on so they will "just work"
    no matter how your server is configured.

CONSTRUCTOR
  new(URL, USERNAME, PASSWORD [, REST_CLIENT_CONFIG])
    The constructor "new()" mimics the constructor for "JIRA::REST", and
    accepts up to four arguments (this documentation is lifted directly from
    "JIRA::REST"'s documentation):

    *   URL

        A string or a URI object denoting the base URL of the JIRA server.
        This is a required argument.

        You may choose a specific API version by appending the
        "/rest/api/VERSION" string to the URL's path. It's more common to
        left it unspecified, in which case the "/rest/api/latest" string is
        appended automatically to the URL.

    *   USERNAME

        The username of a JIRA user.

        It can be undefined if PASSWORD is also undefined. In such a case
        the user credentials are looked up in the ".netrc" file.

    *   PASSWORD

        The HTTP password of the user. (This is the password the user uses
        to log in to JIRA's web interface.)

        It can be undefined, in which case the user credentials are looked
        up in the ".netrc" file.

    *   REST_CLIENT_CONFIG

        A "JIRA::REST" object uses a "REST::Client" object to make the REST
        invocations. This optional argument must be a hash-ref that can be
        fed to the "REST::Client" constructor. Note that the "URL" argument
        overwrites any value associated with the "host" key in this hash.

        To use a network proxy please set the 'proxy' argument to the string
        or URI object describing the fully qualified (including port) URL to
        your network proxy. This is an extension to the "REST::Client"
        configuration and will be removed from the hash before passing it on
        to the "REST::Client" constructor.

METHODS
  issues QUERY
  issues KEY [, KEY...]
    The "issues" method can be called two ways: either by providing a list
    of issue keys, or by proving a single hash reference which describes a
    JIRA query in the same format used by "JIRA::REST" (essentially, jql =>
    "JQL query string").

    The return value is an array of "JIRA::REST::Class::Issue" objects.

  query QUERY
    The "query" method takes a single parameter: a hash reference which
    describes a JIRA query in the same format used by "JIRA::REST"
    (essentially, jql => "JQL query string").

    The return value is a single "JIRA::REST::Class::Query" object.

  iterator QUERY
    The "query" method takes a single parameter: a hash reference which
    describes a JIRA query in the same format used by "JIRA::REST"
    (essentially, jql => "JQL query string"). It accepts an additional
    field, however: restart_if_lt_total. If this field is set to a true
    value, the iterator will keep track of the number of results fetched
    and, if when the results run out this number doesn't match the number of
    results predicted by the query, it will restart the query. This is
    particularly useful if you are transforming a number of issues through
    an iterator, and the transformation causes the issues to no longer match
    the query.

    The return value is a single "JIRA::REST::Class::Iterator" object. The
    issues returned by the query can be obtained in serial by repeatedly
    calling next on this object, which returns a series of
    "JIRA::REST::Class::Issue" objects.

  maxResults
    An accessor that allows setting a global default for maxResults.
    Defaults to 50.

  issue_types
    Returns a list of defined issue types (as
    "JIRA::REST::Class::Issue::Type" objects) for this server.

  projects
    Returns a list of projects (as "JIRA::REST::Class::Project" objects) for
    this server.

  project PROJECT_ID || PROJECT_KEY || PROJECT_NAME
    Returns a "JIRA::REST::Class::Project" object for the project specified.
    Returns undef if the project doesn't exist.

  SSL_verify_none
    Disables the SSL options SSL_verify_mode and verify_hostname on the user
    agent used by this class' "REST::Client" object.

INTERNAL METHODS
  get URL [, QUERY]
    A wrapper for "JIRA::REST"'s GET method.

  post
    Wrapper around "JIRA::REST"'s POST method.

  put
    Wrapper around "JIRA::REST"'s PUT method.

  delete
    Wrapper around "JIRA::REST"'s DELETE method.

  rest_api_url_base
    Returns the base URL for this JIRA server's REST API.

  strip_protocol_and_host
    A method to take the provided URL and strip the protocol and host from
    it.

  url
    An accessor for the URL passed to the "JIRA::REST" object.

  username
    An accessor for the username passed to the "JIRA::REST" object.

  password
    An accessor for the password passed to the "JIRA::REST" object.

  rest_client_config
    An accessor for the REST client config passed to the "JIRA::REST"
    object.

  factory
    An accessor for the "JIRA::REST::Class::Factory".

  JIRA_REST
    An accessor that returns the "JIRA::REST" object being used.

  REST_CLIENT
    An accessor that returns the "REST::Client" object inside the
    "JIRA::REST" object being used.

SEE ALSO
    *   "JIRA::REST"

        "JIRA::REST::Class" uses "JIRA::REST" to perform all its interaction
        with JIRA.

    *   "REST::Client"

        "JIRA::REST" uses a "REST::Client" object to perform its low-level
        interactions.

    *   JIRA REST API Reference
        <https://docs.atlassian.com/jira/REST/latest/>

        Atlassian's official JIRA REST API Reference.

REPOSITORY
    <https://github.com/packy/JIRA-REST-Class>

AUTHOR
    Packy Anderson <packy@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2016 by Packy Anderson.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

