Bug 432914: include_fields and exclude_fields arguments for WebService User.get()

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> r=ghendricks, a=mkanat

2 files changed, 107 insertions, 4 deletions

diff --git a/Bugzilla/WebService/User.pm b/Bugzilla/WebService/User.pm
index e4e5f4b9c..391a799b8 100755
--- a/Bugzilla/WebService/User.pm
+++ b/Bugzilla/WebService/User.pm
@@ -30,6 +30,7 @@ use Bugzilla::Error;
 use Bugzilla::User;
 use Bugzilla::Util qw(trim);
 use Bugzilla::Token;
+use Bugzilla::WebService::Util qw(filter);
 
 # Don't need auth to login
 use constant LOGIN_EXEMPT => {
@@ -144,7 +145,7 @@ sub get {
         if ($params->{ids}){
             ThrowUserError("user_access_by_id_denied");
         }
-        @users = map {{ 
+        @users = map {filter $params, {
                      id => type('int')->value($_->id),
                      real_name => type('string')->value($_->name), 
                      name => type('string')->value($_->login),
@@ -158,7 +159,7 @@ sub get {
 
     # obj_by_ids are only visible to the user if he can see 
     # the otheruser, for non visible otheruser throw an error
-    foreach my $obj (@$obj_by_ids){
+    foreach my $obj (@$obj_by_ids) {
         if (Bugzilla->user->can_see_user($obj)){
             push (@user_objects, $obj) if !$unique_users{$obj->id};
         }
@@ -172,7 +173,7 @@ sub get {
 
     if (Bugzilla->user->in_group('editusers')) {
         @users =
-            map {{
+            map {filter $params, {
                 id => type('int')->value($_->id),
                 real_name => type('string')->value($_->name),
                 name => type('string')->value($_->login),
@@ -185,7 +186,7 @@ sub get {
     }    
     else {
         @users =
-            map {{
+            map {filter $params, {
                 id => type('int')->value($_->id),
                 real_name => type('string')->value($_->name),
                 name => type('string')->value($_->login),
@@ -414,6 +415,34 @@ id of a user they cannot see.
 
 =item C<names> (array) - An array of login names (strings).
 
+=item C<include_fields> (array)
+
+An array of strings, representing the names of keys in the hashes 
+this function returns. Only the fields specified in this hash will be 
+returned, the rest will not be included.
+
+Essentially, this is a way to make the return value smaller, for performance
+or bandwidth reasons.
+
+If you specify an empty array, then this function will return empty hashes.
+
+Invalid field names are ignored.
+
+=item C<exclude_fields> (array)
+
+An array of strings, representing the names of keys in the hashes this 
+function returns. The fields specified will not be excluded from the 
+returned hashes.
+
+Essentially, this is a way to exclude certain fields from the returned
+hashes, for performance or bandwidth reasons.
+
+If you specify all the fields, then this function will return empty hashes.
+
+Invalid field names are ignored.
+
+This overrides C<include_fields>.
+
 =back
 
 =item B<Returns> 
diff --git a/Bugzilla/WebService/Util.pm b/Bugzilla/WebService/Util.pm
new file mode 100644
index 000000000..16fea8c15
--- /dev/null
+++ b/Bugzilla/WebService/Util.pm
@@ -0,0 +1,74 @@
+# -*- 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.
+#
+# The Initial Developer of the Original Code is Everything Solved.
+# Portions created by Everything Solved are Copyright (C) 2008
+# Everything Solved. All Rights Reserved.
+#
+# Contributor(s): Max Kanat-Alexander <mkanat@bugzilla.org>
+
+package Bugzilla::WebService::Util;
+use strict;
+
+use base qw(Exporter);
+
+our @EXPORT_OK = qw(filter);
+
+sub filter ($$) {
+    my ($params, $hash) = @_;
+    my %newhash = %$hash;
+    my %include = map { $_ => 1 } @{ $params->{'include_fields'} || [] };
+    my %exclude = map { $_ => 1 } @{ $params->{'exclude_fields'} || [] };
+
+    foreach my $key (keys %$hash) {
+        if (defined $params->{include_fields}) {
+            delete $newhash{$key} if !$include{$key};
+        }
+        if (defined $params->{exclude_fields}) {
+            delete $newhash{$key} if $exclude{$key};
+        }
+    }
+
+    return \%newhash;
+}
+
+__END__
+
+=head1 NAME
+
+Bugzilla::WebService::Util - Utility functions used inside of the WebService
+code.
+
+=head1 DESCRIPTION
+
+This is somewhat like L<Bugzilla::Util>, but these functions are only used
+internally in the WebService code.
+
+=head1 SYNOPSIS
+
+ filter({ include_fields => ['id', 'name'], 
+          exclude_fields => ['name'] }, $hash);
+
+=head1 METHODS
+
+=over
+
+=item C<filter_fields>
+
+This helps implement the C<include_fields> and C<exclude_fields> arguments
+of WebService methods. Given a hash (the second argument to this subroutine),
+this will remove any keys that are I<not> in C<include_fields> and then remove
+any keys that I<are> in C<exclude_fields>.
+
+=back