Bug 224577: Bugzilla could use a web services interface.

Patch by Marc Schumann <wurblzap@gmail.com>;
r=mkanat; a=myk

1 files changed, 260 insertions, 0 deletions

diff --git a/contrib/bz_webservice_demo.pl b/contrib/bz_webservice_demo.pl
new file mode 100755
index 000000000..a74274cab
--- /dev/null
+++ b/contrib/bz_webservice_demo.pl
@@ -0,0 +1,260 @@
+#!/usr/bin/perl -w
+# -*- Mode: perl; indent-tabs-mode: nil -*-
+#
+# The contents of this file are subject to the Mozilla Public
+# License Version 1.1 (the “License”); you may not use this file
+# except in compliance with the License. You may obtain a copy of
+# the License at http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an “AS
+# IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or
+# implied. See the License for the specific language governing
+# rights and limitations under the License.
+#
+# The Original Code is the Bugzilla Bug Tracking System.
+#
+# Contributor(s): Marc Schumann <wurblzap@gmail.com>
+
+=head1 NAME
+
+bz_webservice_demo.pl - Show how to talk to Bugzilla via XMLRPC
+
+=head1 SYNOPSIS
+
+C<bz_webservice_demo.pl [options]>
+
+C<bz_webservice_demo.pl --help> for detailed help
+
+=cut
+
+use strict;
+use Getopt::Long;
+use Pod::Usage;
+use File::Basename qw(dirname);
+use File::Spec;
+use HTTP::Cookies;
+use XMLRPC::Lite;
+
+# If you want, say “use Bugzilla::WebService::Constants” here to get access
+# to Bugzilla's web service error code constants.
+# If you do this, remember to issue a “use lib” pointing to your Bugzilla
+# installation directory, too.
+
+my $help;
+my $Bugzilla_uri;
+my $Bugzilla_login;
+my $Bugzilla_password;
+my $Bugzilla_remember;
+my $bug_id;
+my $product_name;
+
+GetOptions('help|h|?'       => \$help,
+           'uri=s'          => \$Bugzilla_uri,
+           'login:s'        => \$Bugzilla_login,
+           'password=s'     => \$Bugzilla_password,
+           'rememberlogin!' => \$Bugzilla_remember,
+           'bug_id:s'       => \$bug_id,
+           'product_name:s' => \$product_name,
+          ) or pod2usage({'-verbose' => 0, '-exitval' => 1});
+
+=head1 OPTIONS
+
+=over
+
+=item --help, -h, -?
+
+Print a short help message and exit.
+
+=item --uri
+
+URI to Bugzilla's C<xmlrpc.cgi> script, along the lines of
+C<http://your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi>.
+
+=item --login
+
+Bugzilla login name. Specify this together with B<--password> in order to log in.
+
+Specify this without a value in order to log out.
+
+=item --password
+
+Bugzilla password. Specify this together with B<--login> in order to log in.
+
+=item --rememberlogin
+
+Gives access to Bugzilla's “Bugzilla_remember” option.
+Specify this option while logging in to do the same thing as ticking the
+C<Bugzilla_remember> box on Bugilla's log in form.
+Don't specify this option to do the same thing as unchecking the box.
+
+See Bugzilla's rememberlogin parameter for details.
+
+=item --bug_id
+
+Pass a bug ID to have C<bz_webservice_demo.pl> do some bug-related test calls.
+
+=item --product_name
+
+Pass a product name to have C<bz_webservice_demo.pl> do some product-related
+test calls.
+
+=back
+
+=head1 DESCRIPTION
+
+=cut
+
+pod2usage({'-verbose' => 1, '-exitval' => 0}) if $help;
+_syntaxhelp('URI unspecified') unless $Bugzilla_uri;
+
+# We will use this variable for SOAP call results.
+my $soapresult;
+
+# We will use this variable for function call results.
+my $result;
+
+# Open our cookie jar. We save it into a file so that we may re-use cookies
+# to avoid the need of logging in every time. You're encouraged, but not
+# required, to do this in your applications, too.
+# Cookies are only saved if Bugzilla's rememberlogin parameter is set to one of
+#    - on
+#    - defaulton (and you didn't pass 0 as third parameter to User.login)
+#    - defaultoff (and you passed 1 as third parameter to User.login)
+my $cookie_jar =
+    new HTTP::Cookies('file' => File::Spec->catdir(dirname($0), 'cookies.txt'),
+                      'autosave' => 1);
+
+=head2 Initialization
+
+Using the XMLRPC::Lite class, you set up a proxy, as shown in this script.
+Bugzilla's XMLRPC URI ends in C<xmlrpc.cgi>, so your URI looks along the lines
+of C<http://your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi>.
+
+=cut
+
+my $proxy = XMLRPC::Lite->proxy($Bugzilla_uri,
+                                'cookie_jar' => $cookie_jar);
+
+=head2 Checking Bugzilla's version
+
+To make sure the Bugzilla you're connecting to supports the methods you wish to
+call, you may want to compare the result of C<Bugzilla.get_version> to the
+minimum required version your application needs.
+
+=cut
+
+$soapresult = $proxy->call('Bugzilla.get_version');
+_die_on_fault($soapresult);
+print 'Connecting to a Bugzilla of version ' . $soapresult->result() . ".\n";
+
+=head2 Logging In and Out
+
+=head3 Using Bugzilla's Environment Authentication
+
+Use a
+C<http://login:password@your.bugzilla.installation/path/to/bugzilla/xmlrpc.cgi>
+style URI.
+You don't log out if you're using this kind of authentication.
+
+=head3 Using Bugzilla's CGI Variable Authentication
+
+Use the C<User.login> and C<User.logout> calls to log in and out, as shown
+in this script.
+
+The C<Bugzilla_remember> parameter is optional.
+If omitted, Bugzilla's defaults apply (as specified by its C<rememberlogin>
+parameter).
+
+Bugzilla hands back cookies you'll need to pass along during your work calls.
+
+=cut
+
+if (defined($Bugzilla_login)) {
+    if ($Bugzilla_login ne '') {
+        # Log in.
+        $soapresult = $proxy->call('User.login',
+                                   $Bugzilla_login, $Bugzilla_password,
+                                   $Bugzilla_remember);
+        _die_on_fault($soapresult);
+        print "Login successful.\n";
+    }
+    else {
+        # Log out.
+        $soapresult = $proxy->call('User.logout');
+        _die_on_fault($soapresult);
+        print "Logout successful.\n";
+    }
+}
+
+=head2 Retrieving Bug Information
+
+Call C<Bug.get_bug> with the ID of the bug you want to know more of.
+The call will return a C<Bugzilla::Bug> object.
+
+=cut
+
+if ($bug_id) {
+    $soapresult = $proxy->call('Bug.get_bug', $bug_id);
+    _die_on_fault($soapresult);
+    $result = $soapresult->result;
+
+    foreach (keys(%$result)) {
+        print "$_: $$result{$_}\n";
+    }
+}
+
+=head2 Retrieving Product Information
+
+Call C<Product.get_product> with the name of the product you want to know more
+of.
+The call will return a C<Bugzilla::Product> object.
+
+=cut
+
+if ($product_name) {
+    $soapresult = $proxy->call('Product.get_product', $product_name);
+    _die_on_fault($soapresult);
+    $result = $soapresult->result;
+
+    if (ref($result) eq 'HASH') {
+        foreach (keys(%$result)) {
+            print "$_: $$result{$_}\n";
+        }
+    }
+    else {
+        print "$result\n";
+    }
+}
+
+=head1 NOTES
+
+=head2 Character Set Encoding
+
+Make sure that your application either uses the same character set
+encoding as Bugzilla does, or that it converts correspondingly when using the
+web service API.
+By default, Bugzilla uses UTF-8 as its character set encoding.
+
+=head1 SEE ALSO
+
+There are code comments in C<bz_webservice_demo.pl> which might be of further
+help to you.
+
+=cut
+
+sub _die_on_fault {
+    my $soapresult = shift;
+
+    if ($soapresult->fault) {
+        my ($package, $filename, $line) = caller;
+        die $soapresult->faultcode . ' ' . $soapresult->faultstring .
+            " in SOAP call near $filename line $line.\n";
+    }
+}
+
+sub _syntaxhelp {
+    my $msg = shift;
+
+    print "Error: $msg\n";
+    pod2usage({'-verbose' => 0, '-exitval' => 1});
+}