JIRA::Client - An extended interface to JIRA's SOAP API.

  use JIRA::Client;

  my $jira = JIRA::Client->new('http://jira.example.com/jira', 'user', 'passwd');

  my $issue = $jira->create_issue(
    {
      project => 'TST',
      type => 'Bug',
      summary => 'Summary of the bug',
      assignee => 'gustavo',
      components => ['compa', 'compb'],
      fixVersions => ['1.0.1'],
      custom_fields => {Language => 'Perl', Architecture => 'Linux'},
    }
  );

  $issue = $jira->getIssue('TST-123');

  $jira->set_filter_iterator('my-filter');
  while (my $issue = $jira->next_issue()) {
      # ...
  }

    perldoc JIRA::Client

package JIRA::Client;

use strict;
use warnings;
use Carp;
use SOAP::Lite;

our $VERSION = '0.28';

sub new {
    my ($class, $base_url, $user, $pass, @args) = @_;

    my $soap = SOAP::Lite->proxy("$base_url/rpc/soap/jirasoapservice-v2?wsdl", @args);

    # Make all scalars be encoded as strings by default.
    %{$soap->typelookup()} = (default => [0, sub {1}, 'as_string']);

    my $auth = $soap->login($user, $pass);
    croak $auth->faultcode(), ', ', $auth->faultstring()
        if defined $auth->fault();

    my $self = {
        soap  => $soap,
        auth  => $auth->result(),
        iter  => undef,
        cache => {
            components => {}, # project_key => {name => RemoteComponent}
            versions   => {}, # project_key => {name => RemoteVersion}
        },
    };

    return bless $self, $class;
}

sub DESTROY {
    # FIXME - This call to logout during global destruction in the
    # context of the SVN::Hooks module doesn't work right. When it's
    # called the 'soap' member is undefined for a reason that escapes
    # me so far. Getting rid of the DESTROY method doesn't work either
    # because it would trigger a call to AUTOLOAD which is unable to
    # do it correctly. I think a call to logout is proper here to shut
    # down the SOAP connection cleanly, but it doesn't seem to hurt
    # not to call it.

    # shift->logout();
}

# These are some helper functions to convert names into ids.

sub _convert_type {
    my ($self, $hash) = @_;
    my $type = $hash->{type};
    if ($type =~ /\D/) {
        my $types = $self->get_issue_types();
        croak "There is no issue type called '$type'.\n"
            unless exists $types->{$type};
        $hash->{type} = $types->{$type}{id};
    }
    return;
}

sub _convert_priority {
    my ($self, $hash) = @_;
    my $prio = $hash->{priority};
    if ($prio =~ /\D/) {
        my $prios = $self->get_priorities();
        croak "There is no priority called '$prio'.\n"
            unless exists $prios->{$prio};
        $hash->{priority} = $prios->{$prio}{id};
    }
    return;
}

sub _convert_resolution {
    my ($self, $hash) = @_;
    my $resolution = $hash->{resolution};
    if ($resolution =~ /\D/) {
        my $resolutions = $self->get_resolutions();
        croak "There is no resolution called '$resolution'.\n"
            unless exists $resolutions->{$resolution};
        $hash->{resolution} = $resolutions->{$resolution}{id};
    }
    return;
}

sub _convert_security_level {
    my ($self, $seclevel) = @_;
    if ($seclevel =~ /\D/) {
        my $seclevels = $self->get_security_levels();
        croak "There is no security level called '$seclevel'.\n"
            unless exists $seclevels->{$seclevel};
        $seclevel = $seclevels->{$seclevel}{id};
    }
    return $seclevel;
}

sub _convert_components {
    my ($self, $hash, $key, $project) = @_;
    my $comps = $hash->{components};
    croak "The 'components' value must be an ARRAY ref.\n"
       unless ref $comps && ref $comps eq 'ARRAY';
    my $pcomps;                 # project components
    foreach my $c (@{$comps}) {
       next if ref $c;
       if ($c =~ /\D/) {
           # It's a component name. Let us convert it into its id.
	   croak "Cannot convert component names because I don't know for which project.\n"
	       unless $project;
           $pcomps = $self->get_components($project) unless defined $pcomps;
           croak "There is no component called '$c'.\n" unless exists $pcomps->{$c};
           $c = $pcomps->{$c}{id};
       }
       # Now we can convert it into an object.
       $c = RemoteComponent->new($c);
    }
    return;
}

sub _convert_versions {
    my ($self, $hash, $key, $project) = @_;
    my $versions = $hash->{$key};
    croak "The '$versions' value must be a ARRAY ref.\n"
       unless ref $versions && ref $versions eq 'ARRAY';
    my $pversions;
    foreach my $v (@{$versions}) {
       next if ref $v;
       if ($v =~ /\D/) {
           # It is a version name. Let us convert it into its id.
	   croak "Cannot convert version names because I don't know for which project.\n"
	       unless $project;
           $pversions = $self->get_versions($project) unless defined $pversions;
           croak "There is no version called '$v'.\n" unless exists $pversions->{$v};
           $v = $pversions->{$v}{id};
       }
       # Now we can convert it into an object.
       $v = RemoteVersion->new($v);
    }
    return;
}

sub _convert_duedate {
    my ($self, $hash) = @_;
    my $duedate = $hash->{duedate};
    if (ref $duedate) {
	croak "duedate fields must be set with DateTime references.\n"
	    unless ref $duedate eq 'DateTime';
	$hash->{duedate} = $duedate->strftime('%d/%B/%y');
    }
    elsif (my ($year, $month, $day) = ($duedate =~ /^(\d{4})-(\d{2})-(\d{2})/)) {
	$month >= 1 and $month <= 12
	    or croak "Invalid duedate ($hash->{duedate})";
	$hash->{duedate} = join(
	    '/',
	    $day,
	    qw/zero Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec/[$month],
	    substr($year, 2, 2),
	);
    }
    return;
}

sub _convert_custom_fields {
    my ($self, $hash) = @_;
    my $custom_fields = $hash->{custom_fields};
    croak "The 'custom_fields' value must be a HASH ref.\n"
        unless ref $custom_fields && ref $custom_fields eq 'HASH';
    my %id2values;
    while (my ($id, $values) = each %$custom_fields) {
	my $realid = $id;
        unless ($realid =~ /^customfield_\d+$/) {
            my $cfs = $self->get_custom_fields();
            croak "Can't find custom field named '$id'.\n"
                unless exists $cfs->{$id};
            $realid = $cfs->{$id}{id};
        }

	# Custom field values must be specified as ARRAYs but we allow for some short-cuts.
	if (! ref $values) {
	    $id2values{$realid} = [$values];
	} elsif (ref $values eq 'ARRAY') {
	    $id2values{$realid} = $values;
	} elsif (ref $values eq 'HASH') {
	    # This is a short-cut for a Cascading select field, which
	    # must be specified like this: http://tinyurl.com/2bmthoa
	    # The short-cut requires a HASH where each cascading level
	    # is indexed by its level number, starting at zero.
	    foreach my $level (sort {$a <=> $b} keys %$values) {
		my $level_values = $values->{$level};
		$level_values = [$level_values] unless ref $level_values;
		if ($level eq '0') {
		    # The first level doesn't have a colon
		    $id2values{$realid} = $level_values
		} elsif ($level =~ /^\d+$/) {
		    $id2values{"$realid:$level"} = $level_values;
		} else {
		    croak "Invalid cascading field values level spec ($level). It must be a natural number.\n";
		}
	    }
	} else {
	    croak "Custom field '$id' got a '", ref($values), "' reference as a value.\nValues can only be specified as scalars, ARRAYs, or HASHes though.\n";
	}
    }
    $hash->{custom_fields} = \%id2values;
    return;
}

my %_converters = (
    affectsVersions => \&_convert_versions,
    components      => \&_convert_components,
    custom_fields   => \&_convert_custom_fields,
    duedate         => \&_convert_duedate,
    fixVersions     => \&_convert_versions,
    priority        => \&_convert_priority,
    resolution      => \&_convert_resolution,
    type            => \&_convert_type,
);

sub create_issue
{
    my ($self, $hash, $seclevel) = @_;
    croak "create_issue requires an argument.\n"
        unless defined $hash;
    croak "create_issue's argument must be a HASH ref.\n"
        unless ref $hash && ref $hash eq 'HASH';
    for my $field (qw/project summary type/) {
        croak "create_issue's HASH ref must define a '$field'.\n"
            unless exists $hash->{$field};
    }

    # Convert some fields' values
    foreach my $field (grep {exists $_converters{$_}} keys %$hash) {
	$_converters{$field}->($self, $hash, $field, $hash->{project});
    }

    # Substitute customFieldValues for custom_fields
    if (my $cfs = delete $hash->{custom_fields}) {
        $hash->{customFieldValues} = [map {RemoteCustomFieldValue->new($_, $cfs->{$_})} keys %$cfs];
    }

    if (defined $seclevel) {
	return $self->createIssueWithSecurityLevel($hash, _convert_security_level($self, $seclevel));
    }
    else {
	return $self->createIssue($hash);
    }
}

sub update_issue
{
    my ($self, $issue, $params) = @_;
    my $key;
    if (ref $issue) {
	croak "update_issue's first argument must be a RemoteIssue reference.\n"
	    unless ref $issue eq 'RemoteIssue';
	$key = $issue->{key};
    }
    else {
	$key = $issue;
	$issue = $self->getIssue($key);
    }

    croak "update_issue requires two arguments.\n"
        unless defined $params;
    croak "update_issue's second argument must be a HASH ref.\n"
        unless ref $params && ref $params eq 'HASH';

    my ($project) = ($key =~ /^([^-]+)/);

    # Convert some fields' values
    foreach my $field (grep {exists $_converters{$_}} keys %$params) {
	$_converters{$field}->($self, $params, $field, $project);
    }

    # Convert RemoteComponent objects into component ids
    if (my $comps = $params->{components}) {
        $_ = $_->{id} foreach @$comps;
    }

    # Convert RemoteVersion objects into version ids
    for my $field (qw/fixVersions affectsVersions/) {
        if (my $versions = $params->{$field}) {
            $_ = $_->{id} foreach @$versions;
        }
    }
    # Due to a bug in JIRA
    # (http://jira.atlassian.com/browse/JRA-12300) we have to
    # substitute 'versions' for the 'affectsVersions' key
    if (my $versions = delete $params->{affectsVersions}) {
        $params->{versions} = $versions;
    }

    # Expand the custom_fields hash into the custom fields themselves.
    if (my $custom_fields = delete $params->{custom_fields}) {
        while (my ($id, $values) = each %$custom_fields) {
            $params->{$id} = $values;
        }
    }

    return $self->updateIssue($key, $params);
}

sub get_issue_types {
    my ($self) = @_;
    $self->{cache}{issue_types} ||= {map {$_->{name} => $_} @{$self->getIssueTypes()}};
    return $self->{cache}{issue_types};
}

sub get_statuses {
    my ($self) = @_;
    $self->{cache}{statuses} ||= {map {$_->{name} => $_} @{$self->getStatuses()}};
    return $self->{cache}{statuses};
}

sub get_priorities {
    my ($self) = @_;
    $self->{cache}{priorities} ||= {map {$_->{name} => $_} @{$self->getPriorities()}};
    return $self->{cache}{priorities};
}

sub get_resolutions {
    my ($self) = @_;
    $self->{cache}{resolutions} ||= {map {$_->{name} => $_} @{$self->getResolutions()}};
    return $self->{cache}{resolutions};
}

sub get_security_levels {
    my ($self) = @_;
    $self->{cache}{seclevels} ||= {map {$_->{name} => $_} @{$self->getSecurityLevels()}};
    return $self->{cache}{seclevels};
}

sub get_custom_fields {
    my ($self) = @_;
    $self->{cache}{custom_fields} ||= {map {$_->{name} => $_} @{$self->getCustomFields()}};
    return $self->{cache}{custom_fields};
}

sub set_custom_fields {
    my ($self, $cfs) = @_;
    $self->{cache}{custom_fields} = $cfs;
    return;
}

sub get_components {
    my ($self, $project_key) = @_;
    $self->{cache}{components}{$project_key} ||= {map {$_->{name} => $_} @{$self->getComponents($project_key)}};
    return $self->{cache}{components}{$project_key};
}

sub get_versions {
    my ($self, $project_key) = @_;
    $self->{cache}{versions}{$project_key} ||= {map {$_->{name} => $_} @{$self->getVersions($project_key)}};
    return $self->{cache}{versions}{$project_key};
}

sub get_favourite_filters {
    my ($self) = @_;
    $self->{cache}{filters} ||= {map {$_->{name} => $_} @{$self->getFavouriteFilters()}};
    return $self->{cache}{filters};
}

sub set_filter_iterator {
    my ($self, $filter, $cache_size) = @_;

    if ($filter =~ /\D/) {
        my $filters = $self->getSavedFilters();
        foreach my $f (@$filters) {
            if ($f->{name} eq $filter) {
                $filter = $f->{id};
                last;
            }
        }
        croak "Can't find filter '$filter'\n" if $filter =~ /\D/;
    }

    if ($cache_size) {
        croak "set_filter_iterator's second arg must be a number ($cache_size).\n"
            if $cache_size =~ /\D/;
    }

    $self->{iter} = {
        id     => $filter,
        offset => 0,  # offset to be used in the next call to getIssuesFromFilterWithLimit
        issues => [], # issues returned by the last call to getIssuesFromFilterWithLimit
        size   => $cache_size || 128,
    };

    return;
}

sub next_issue {
    my ($self) = @_;
    defined $self->{iter}
        or croak "You must call setFilterIterator before calling nextIssue\n";
    my $iter = $self->{iter};
    if (@{$iter->{issues}} == 0) {
        if ($iter->{id}) {
            my $issues = eval {$self->getIssuesFromFilterWithLimit($iter->{id}, $iter->{offset}, $iter->{size})};
            if ($@) {
                # The getIssuesFromFilterWithLimit appeared in JIRA
                # 3.13.4. Before that we had to use the unsafe
                # getIssuesFromFilter. Here we detect that we're talking
                # with an old JIRA and resort to the deprecated method
                # instead.
                croak $@ unless $@ =~ /No such operation/;
                $iter->{issues} = $self->getIssuesFromFilter($iter->{id});
                $iter->{id}     = undef;
            }
            elsif (@$issues) {
                $iter->{offset} += @$issues;
                $iter->{issues}  =  $issues;
            }
            else {
                $self->{iter} = undef;
                return;
            }
        }
        else {
            return;
        }
    }
    return shift @{$iter->{issues}};
}

sub progress_workflow_action_safely {
    my ($self, $key, $action, $params) = @_;
    my $issue;
    if (ref $key) {
        $issue = $key;
        $key   = $issue->{key};
    }
    my ($project) = (split /-/, $key)[0];
    $params = {} unless defined $params;
    ref $params and ref $params eq 'HASH'
        or croak "progress_workflow_action_safely's third arg must be a HASH-ref\n";

    # Grok the action id if it's not a number
    if ($action =~ /\D/) {
        my @available_actions = @{$self->getAvailableActions($key)};
        my @named_actions     = grep {$action eq $_->{name}} @available_actions;
        if (@named_actions) {
            $action = $named_actions[0]->{id};
        }
        else {
            croak "Unavailable action ($action).\n";
        }
    }

    # Make sure $params contains all the fields that are present in
    # the action screen.
    my @fields = @{$self->getFieldsForAction($key, $action)};
    foreach my $id (map {$_->{id}} @fields) {
        # This is due to a bug in JIRA
        # http://jira.atlassian.com/browse/JRA-12300
        $id = 'affectsVersions' if $id eq 'versions';

        next if exists $params->{$id};

        $issue = $self->getIssue($key) unless defined $issue;
        if (exists $issue->{$id}) {
            $params->{$id} = $issue->{$id} if defined $issue->{$id};
        }
        else {
            foreach my $cf (@{$issue->{customFieldValues}}) {
                if ($cf->{customfieldId} eq $id) {
                    $params->{$id} = $cf->{values};
                    last;
                }
            }
            # NOTE: It's not a problem if we can't find a missing
            # parameter in the issue. It will simply stay undefined.
        }
    }

    # Convert some fields' values
    foreach my $field (grep {exists $_converters{$_}} keys %$params) {
	$_converters{$field}->($self, $params, $field, $project);
    }

    # Convert RemoteComponent objects into component ids
    if (my $comps = $params->{components}) {
        $_ = $_->{id} foreach @$comps;
    }

    # Convert RemoteVersion objects into version ids
    for my $field (qw/fixVersions affectsVersions/) {
        if (my $versions = $params->{$field}) {
            $_ = $_->{id} foreach @$versions;
        }
    }
    # Due to a bug in JIRA
    # (http://jira.atlassian.com/browse/JRA-12300) we have to
    # substitute 'versions' for the 'affectsVersions' key
    if (my $versions = delete $params->{affectsVersions}) {
        $params->{versions} = $versions;
    }

    # Expand the custom_fields hash into the custom fields themselves.
    if (my $custom_fields = delete $params->{custom_fields}) {
        while (my ($id, $values) = each %$custom_fields) {
            $params->{$id} = $values;
        }
    }

    return $self->progressWorkflowAction($key, $action, $params);
}

sub get_issue_custom_field_values {
    my ($self, $issue, @cfs) = @_;
    my @values;
    my $cfs;
  CUSTOM_FIELD:
    foreach my $cf (@cfs) {
        unless ($cf =~ /^customfield_\d+$/) {
            $cfs = $self->get_custom_fields() unless defined $cfs;
            croak "Can't find custom field named '$cf'.\n"
                unless exists $cfs->{$cf};
            $cf = $cfs->{$cf}{id};
        }
        foreach my $rcfv (@{$issue->{customFieldValues}}) {
            if ($rcfv->{customfieldId} eq $cf) {
                push @values, $rcfv->{values};
                next CUSTOM_FIELD;
            }
        }
        push @values, undef;    # unset custom field
    }
    return wantarray ? @values : \@values;
}

sub attach_files_to_issue {
    my ($self, $issue, @files) = @_;

    # First we process the @files specification. Filenames are pushed
    # in @filenames and @attachments will end up with IO objects from
    # which the file contents are going to be read later.

    my (@filenames, @attachments);

    for my $file (@files) {
	if (not ref $file) {
	    require File::Basename;
	    push @filenames, File::Basename::basename($file);
	    open my $fh, '<:raw', $file
		or croak "Can't open $file: $!\n";
	    push @attachments, $fh;
	}
	elsif (ref $file eq 'HASH') {
	    while (my ($name, $contents) = each %$file) {
		push @filenames, $name;
		if (not ref $contents) {
		    open my $fh, '<:raw', $contents
			or croak "Can't open $contents: $!\n";
		    push @attachments, $fh;
		} elsif (ref($contents) =~ /^(?:GLOB|IO::File|FileHandle)$/) {
		    push @attachments, $contents;
		} else {
		    croak "Invalid content specification for file $name.\n";
		}
	    }
	}
	else {
	    croak "Files must be specified by STRINGs or HASHes, not by " . ref($file) . "s\n";
	}
    }

    # Now we have to read all file contents and encode them to Base64.

    require MIME::Base64;
    for my $i (0 .. $#attachments) {
	my $fh = $attachments[$i];
	my $attachment = '';
	my $chars_read;
	while ($chars_read = read $fh, my $buf, 57*72) {
	    $attachment .= MIME::Base64::encode_base64($buf);
	}
	defined $chars_read
	    or croak "Error reading '$filenames[$i]': $!\n";
	length $attachment
	    or croak "Can't attach empty file '$filenames[$i]'\n";
	$attachments[$i] = $attachment;
    }

    return $self->addBase64EncodedAttachmentsToIssue($issue, \@filenames, \@attachments);
}

sub attach_strings_to_issue {
    my ($self, $issue, $hash) = @_;

    require MIME::Base64;

    my (@filenames, @attachments);

    while (my ($filename, $contents) = each %$hash) {
	push @filenames,   $filename;
	push @attachments, MIME::Base64::encode_base64($contents);
    }

    return $self->addBase64EncodedAttachmentsToIssue($issue, \@filenames, \@attachments);
}

package RemoteFieldValue;

sub new {
    my ($class, $id, $values) = @_;

    # This is due to a bug in JIRA
    # http://jira.atlassian.com/browse/JRA-12300
    $id = 'versions' if $id eq 'affectsVersions';

    $values = [$values] unless ref $values;
    return bless({id => $id, values => $values}, $class);
}

package RemoteCustomFieldValue;

sub new {
    my ($class, $id, $values) = @_;

    $values = [$values] unless ref $values;
    return bless({customfieldId => $id, key => undef, values => $values} => $class);
}

package RemoteComponent;

sub new {
    my ($class, $id, $name) = @_;
    my $o = bless({id => $id}, $class);
    $o->{name} = $name if $name;
    return $o;
}

package RemoteVersion;

sub new {
    my ($class, $id, $name) = @_;
    my $o = bless({id => $id}, $class);
    $o->{name} = $name if $name;
    return $o;
}

package JIRA::Client;

# Almost all of the JIRA API parameters are strings. The %typeof hash
# specifies the exceptions. It maps a method name to a hash mapping a
# parameter position to its type. (The parameter position is
# zero-based, after the authentication token.

my %typeof = (
    addActorsToProjectRole                   => {1 => \&_cast_remote_project_role},
    addAttachmentsToIssue              	     => \&_cast_attachments,
    addBase64EncodedAttachmentsToIssue 	     => \&_cast_base64encodedattachments,
    addComment                         	     => {0 => \&_cast_issue_key, 1 => \&_cast_remote_comment},
    addDefaultActorsToProjectRole            => {1 => \&_cast_remote_project_role},
    addWorklogAndAutoAdjustRemainingEstimate => {0 => \&_cast_issue_key},
    addWorklogAndRetainRemainingEstimate     => {0 => \&_cast_issue_key},
    addWorklogWithNewRemainingEstimate       => {0 => \&_cast_issue_key},
    archiveVersion                     	     => {2 => 'boolean'},
    createIssueWithSecurityLevel       	     => {1 => 'long'},
    createProjectRole                        => {0 => \&_cast_remote_project_role},
    deleteIssue                 	     => {0 => \&_cast_issue_key},
    deleteProjectAvatar                	     => {0 => 'long'},
    deleteProjectRole                  	     => {0 => \&_cast_remote_project_role, 1 => 'boolean'},
    getAssociatedNotificationSchemes         => {0 => \&_cast_remote_project_role},
    getAssociatedPermissionSchemes           => {0 => \&_cast_remote_project_role},
    getAttachmentsFromIssue           	     => {0 => \&_cast_issue_key},
    getAvailableActions           	     => {0 => \&_cast_issue_key},
    getComment                         	     => {0 => 'long'},
    getComments                        	     => {0 => \&_cast_issue_key},
    getDefaultRoleActors                     => {0 => \&_cast_remote_project_role},
    getFieldsForAction                 	     => {0 => \&_cast_issue_key},
    getFieldsForEdit                 	     => {0 => \&_cast_issue_key},
    getIssue	                 	     => {0 => \&_cast_issue_key},
    getIssueCountForFilter             	     => {0 => \&_cast_filter_name_to_id},
    getIssuesFromFilter                	     => {0 => \&_cast_filter_name_to_id},
    getIssuesFromFilterWithLimit       	     => {0 => \&_cast_filter_name_to_id, 1 => 'int', 2 => 'int'},
    getIssuesFromJqlSearch             	     => {1 => 'int'},
    getIssuesFromTextSearchWithLimit   	     => {1 => 'int', 2 => 'int'},
    getIssuesFromTextSearchWithProject 	     => {2 => 'int'},
    getProjectAvatars                  	     => {1 => 'boolean'},
    getProjectById                     	     => {0 => 'long'},
    getProjectRole                     	     => {0 => 'long'},
    getProjectRoleActors               	     => {0 => \&_cast_remote_project_role},
    getProjectWithSchemesById          	     => {0 => 'long'},
    getResolutionDateById              	     => {0 => 'long'},
    getResolutionDateByKey             	     => {0 => \&_cast_issue_key},
    getSecurityLevel             	     => {0 => \&_cast_issue_key},
    getWorklogs		             	     => {0 => \&_cast_issue_key},
    hasPermissionToCreateWorklog       	     => {0 => \&_cast_issue_key},
    progressWorkflowAction             	     => {0 => \&_cast_issue_key, 2 => \&_cast_remote_field_values},
    removeActorsFromProjectRole              => {1 => \&_cast_remote_project_role},
    removeDefaultActorsFromProjectRole       => {1 => \&_cast_remote_project_role},
    setProjectAvatar                   	     => {1 => 'long'},
    updateIssue                        	     => {0 => \&_cast_issue_key, 1 => \&_cast_remote_field_values},
    updateProjectRole                        => {0 => \&_cast_remote_project_role},
);

sub _cast_issue_key {
    my ($self, $issue) = @_;
    return ref $issue ? $issue->{key} : $issue;
}

sub _cast_remote_comment {
    my ($self, $arg) = @_;
    return ref $arg ? $arg : bless({body => $arg} => 'RemoteComment');
}

sub _cast_filter_name_to_id {
    my ($self, $arg) = @_;
    ref $arg and croak "Filter arg must be a scalar, not a ", ref($arg), "\n";
    return $arg unless $arg =~ /\D/;
    my $filters = $self->get_favourite_filters();
    exists $filters->{$arg} or croak "Unknown filter: $arg\n";
    return $filters->{$arg}{id};
}

sub _cast_remote_field_values {
    my ($self, $arg) = @_;
    if (ref $arg && ref $arg eq 'HASH') {
	return [map {RemoteFieldValue->new($_, $arg->{$_})} keys %$arg];
    }
    return $arg;
}

sub _cast_remote_project_role {
    my ($self, $arg) = @_;
    if (ref $arg && ref $arg eq 'RemoteProjectRole' && exists $arg->{id} && ! ref $arg->{id}) {
	$arg->{id} = SOAP::Data->type(long => $arg->{id});
    }
    return $arg;
}

sub _cast_attachments {
    my ($self, $method, $args) = @_;
    # The addAttachmentsToIssue method is deprecated and requires too
    # much overhead to pass the file contents over the wire. Here we
    # convert the arguments to call the newer
    # addBase64EncodedAttachmentsToIssue method instead.
    require MIME::Base64;
    for my $content (@{$args->[2]}) {
	$content = MIME::Base64::encode_base64($content);
    }
    $$method = 'addBase64EncodedAttachmentsToIssue';
    _cast_base64encodedattachments($self, $method, $args);
    return;
}

sub _cast_base64encodedattachments {
    my ($self, $method, $args) = @_;
    $args->[0] = _cast_issue_key($self, $args->[0]);
    # We have to set the names of the arrays and of its elements
    # because the default naming isn't properly understood by JIRA.
    for my $i (1 .. 2) {
	$args->[$i] = SOAP::Data->name(
	    "array$i",
	    [map {SOAP::Data->name("elem$i", $_)} @{$args->[$i]}],
	);
    }
    return;
}

# All methods follow the same call convention, which makes it easy to
# implement them all with an AUTOLOAD.

our $AUTOLOAD;
sub AUTOLOAD {
    my ($self, @args) = @_;
    (my $method = $AUTOLOAD) =~ s/.*:://;

    # Perform any non-default type coersion
    if (my $typeof = $typeof{$method}) {
	if (ref $typeof eq 'HASH') {
	    while (my ($i, $type) = each %$typeof) {
		if (ref $type) {
		    ref $type eq 'CODE'
			or croak "Invalid coersion spec to (", ref($type), ").\n";
		    $args[$i] = $type->($self, $args[$i]);
		} elsif (! ref $args[$i]) {
		    $args[$i] = SOAP::Data->type($type => $args[$i]);
		} elsif (ref $args[$i] eq 'ARRAY') {
		    foreach (@{$args[$i]}) {
			$_ = SOAP::Data->type($type => $_);
		    }
		} elsif (ref $args[$i] eq 'HASH') {
		    foreach (values %{$args[$i]}) {
			$_ = SOAP::Data->type($type => $_);
		    }
		} else {
		    croak "Can't coerse argument $i of method $AUTOLOAD.\n";
		}
	    }
	}
	elsif (ref $typeof eq 'CODE') {
	    $typeof->($self, \$method, \@args);
	}
    }

    my $call = $self->{soap}->call($method, $self->{auth}, @args);
    croak $call->faultcode(), ', ', $call->faultstring()
        if defined $call->fault();
    return $call->result();
}

1; # End of JIRA::Client