Series.pm

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This Source Code Form is "Incompatible With Secondary Licenses", as
# defined by the Mozilla Public License, v. 2.0.

# This module implements a series - a set of data to be plotted on a chart.
#
# This Series is in the database if and only if self->{'series_id'} is defined. 
# Note that the series being in the database does not mean that the fields of 
# this object are the same as the DB entries, as the object may have been 
# altered.

package Bugzilla::Series;

use 5.10.1;
use strict;

use Bugzilla::Error;
use Bugzilla::Util;

# This is a hack so that we can re-use the rename_field_value
# code from Bugzilla::Search::Saved.
use constant DB_TABLE => 'series';
use constant ID_FIELD => 'series_id';

sub new {
    my $invocant = shift;
    my $class = ref($invocant) || $invocant;
  
    # Create a ref to an empty hash and bless it
    my $self = {};
    bless($self, $class);

    my $arg_count = scalar(@_);
    
    # new() can return undef if you pass in a series_id and the user doesn't 
    # have sufficient permissions. If you create a new series in this way,
    # you need to check for an undef return, and act appropriately.
    my $retval = $self;

    # There are three ways of creating Series objects. Two (CGI and Parameters)
    # are for use when creating a new series. One (Database) is for retrieving
    # information on existing series.
    if ($arg_count == 1) {
        if (ref($_[0])) {
            # We've been given a CGI object to create a new Series from.
            # This series may already exist - external code needs to check
            # before it calls writeToDatabase().
            $self->initFromCGI($_[0]);
        }
        else {
            # We've been given a series_id, which should represent an existing
            # Series.
            $retval = $self->initFromDatabase($_[0]);
        }
    }
    elsif ($arg_count >= 6 && $arg_count <= 8) {
        # We've been given a load of parameters to create a new Series from.
        # Currently, undef is always passed as the first parameter; this allows
        # you to call writeToDatabase() unconditionally.
        # XXX - You cannot set category_id and subcategory_id from here.
        $self->initFromParameters(@_);
    }
    else {
        die("Bad parameters passed in - invalid number of args: $arg_count");
    }

    return $retval;
}

sub initFromDatabase {
    my ($self, $series_id) = @_;
    my $dbh = Bugzilla->dbh;
    my $user = Bugzilla->user;

    detaint_natural($series_id) 
      || ThrowCodeError("invalid_series_id", { 'series_id' => $series_id });

    my $grouplist = $user->groups_as_string;

    my @series = $dbh->selectrow_array("SELECT series.series_id, cc1.name, " .
        "cc2.name, series.name, series.creator, series.frequency, " .
        "series.query, series.is_public, series.category, series.subcategory " .
        "FROM series " .
        "INNER JOIN series_categories AS cc1 " .
        "    ON series.category = cc1.id " .
        "INNER JOIN series_categories AS cc2 " .
        "    ON series.subcategory = cc2.id " .
        "LEFT JOIN category_group_map AS cgm " .
        "    ON series.category = cgm.category_id " .
        "    AND cgm.group_id NOT IN($grouplist) " .
        "WHERE series.series_id = ? " .
        "    AND (creator = ? OR (is_public = 1 AND cgm.category_id IS NULL))",
        undef, ($series_id, $user->id));

    if (@series) {
        $self->initFromParameters(@series);
        return $self;
    }
    else {
        return undef;
    }
}

sub initFromParameters {
    # Pass undef as the first parameter if you are creating a new series.
    my $self = shift;

    ($self->{'series_id'}, $self->{'category'},  $self->{'subcategory'},
     $self->{'name'}, $self->{'creator_id'}, $self->{'frequency'},
     $self->{'query'}, $self->{'public'}, $self->{'category_id'},
     $self->{'subcategory_id'}) = @_;

    # If the first parameter is undefined, check if this series already
    # exists and update it series_id accordingly
    $self->{'series_id'} ||= $self->existsInDatabase();
}

sub initFromCGI {
    my $self = shift;
    my $cgi = shift;

    $self->{'series_id'} = $cgi->param('series_id') || undef;
    if (defined($self->{'series_id'})) {
        detaint_natural($self->{'series_id'})
          || ThrowCodeError("invalid_series_id", 
                               { 'series_id' => $self->{'series_id'} });
    }
    
    $self->{'category'} = $cgi->param('category')
      || $cgi->param('newcategory')
      || ThrowUserError("missing_category");

    $self->{'subcategory'} = $cgi->param('subcategory')
      || $cgi->param('newsubcategory')
      || ThrowUserError("missing_subcategory");

    $self->{'name'} = $cgi->param('name')
      || ThrowUserError("missing_name");

    $self->{'creator_id'} = Bugzilla->user->id;

    $self->{'frequency'} = $cgi->param('frequency');
    detaint_natural($self->{'frequency'})
      || ThrowUserError("missing_frequency");

    $self->{'query'} = $cgi->canonicalise_query("format", "ctype", "action",
                                        "category", "subcategory", "name",
                                        "frequency", "public", "query_format");
    trick_taint($self->{'query'});
                                        
    $self->{'public'} = $cgi->param('public') ? 1 : 0;
    
    # Change 'admin' here and in series.html.tmpl, or remove the check
    # completely, if you want to change who can make series public.
    $self->{'public'} = 0 unless Bugzilla->user->in_group('admin');
}

sub writeToDatabase {
    my $self = shift;

    my $dbh = Bugzilla->dbh;
    $dbh->bz_start_transaction();

    my $category_id = getCategoryID($self->{'category'});
    my $subcategory_id = getCategoryID($self->{'subcategory'});

    my $exists;
    if ($self->{'series_id'}) { 
        $exists = 
            $dbh->selectrow_array("SELECT series_id FROM series
                                   WHERE series_id = $self->{'series_id'}");
    }
    
    # Is this already in the database?                              
    if ($exists) {
        # Update existing series
        my $dbh = Bugzilla->dbh;
        $dbh->do("UPDATE series SET " .
                 "category = ?, subcategory = ?," .
                 "name = ?, frequency = ?, is_public = ?  " .
                 "WHERE series_id = ?", undef,
                 $category_id, $subcategory_id, $self->{'name'},
                 $self->{'frequency'}, $self->{'public'}, 
                 $self->{'series_id'});
    }
    else {
        # Insert the new series into the series table
        $dbh->do("INSERT INTO series (creator, category, subcategory, " .
                 "name, frequency, query, is_public) VALUES " . 
                 "(?, ?, ?, ?, ?, ?, ?)", undef,
                 $self->{'creator_id'}, $category_id, $subcategory_id, $self->{'name'},
                 $self->{'frequency'}, $self->{'query'}, $self->{'public'});

        # Retrieve series_id
        $self->{'series_id'} = $dbh->selectrow_array("SELECT MAX(series_id) " .
                                                     "FROM series");
        $self->{'series_id'}
          || ThrowCodeError("missing_series_id", { 'series' => $self });
    }
    
    $dbh->bz_commit_transaction();
}

# Check whether a series with this name, category and subcategory exists in
# the DB and, if so, returns its series_id.
sub existsInDatabase {
    my $self = shift;
    my $dbh = Bugzilla->dbh;

    my $category_id = getCategoryID($self->{'category'});
    my $subcategory_id = getCategoryID($self->{'subcategory'});
    
    trick_taint($self->{'name'});
    my $series_id = $dbh->selectrow_array("SELECT series_id " .
                              "FROM series WHERE category = $category_id " .
                              "AND subcategory = $subcategory_id AND name = " .
                              $dbh->quote($self->{'name'}));
                              
    return($series_id);
}

# Get a category or subcategory IDs, creating the category if it doesn't exist.
sub getCategoryID {
    my ($category) = @_;
    my $category_id;
    my $dbh = Bugzilla->dbh;

    # This seems for the best idiom for "Do A. Then maybe do B and A again."
    while (1) {
        # We are quoting this to put it in the DB, so we can remove taint
        trick_taint($category);

        $category_id = $dbh->selectrow_array("SELECT id " .
                                      "from series_categories " .
                                      "WHERE name =" . $dbh->quote($category));

        last if defined($category_id);

        $dbh->do("INSERT INTO series_categories (name) " .
                 "VALUES (" . $dbh->quote($category) . ")");
    }

    return $category_id;
}

##########
# Methods
##########
sub id   { return $_[0]->{'series_id'}; }
sub name { return $_[0]->{'name'}; }

sub creator {
    my $self = shift;

    if (!$self->{creator} && $self->{creator_id}) {
        require Bugzilla::User;
        $self->{creator} = new Bugzilla::User($self->{creator_id});
    }
    return $self->{creator};
}

sub remove_from_db {
    my $self = shift;
    my $dbh = Bugzilla->dbh;

    $dbh->do('DELETE FROM series WHERE series_id = ?', undef, $self->id);
}

1;

=head1 B<Methods in need of POD>

=over

=item creator

=item existsInDatabase

=item name

=item getCategoryID

=item initFromParameters

=item initFromCGI

=item initFromDatabase

=item remove_from_db

=item writeToDatabase

=item id

=back