2009-04-16 Eric Roman <eroman@chromium.org>
[WebKit-https.git] / BugsSite / Bugzilla.pm
1 # -*- Mode: perl; indent-tabs-mode: nil -*-
2 #
3 # The contents of this file are subject to the Mozilla Public
4 # License Version 1.1 (the "License"); you may not use this file
5 # except in compliance with the License. You may obtain a copy of
6 # the License at http://www.mozilla.org/MPL/
7 #
8 # Software distributed under the License is distributed on an "AS
9 # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
10 # implied. See the License for the specific language governing
11 # rights and limitations under the License.
12 #
13 # The Original Code is the Bugzilla Bug Tracking System.
14 #
15 # The Initial Developer of the Original Code is Netscape Communications
16 # Corporation. Portions created by Netscape are
17 # Copyright (C) 1998 Netscape Communications Corporation. All
18 # Rights Reserved.
19 #
20 # Contributor(s): Bradley Baetz <bbaetz@student.usyd.edu.au>
21 #                 Erik Stambaugh <erik@dasbistro.com>
22 #
23
24 package Bugzilla;
25
26 use strict;
27
28 use Bugzilla::Auth;
29 use Bugzilla::Auth::Login::WWW;
30 use Bugzilla::CGI;
31 use Bugzilla::Config;
32 use Bugzilla::Constants;
33 use Bugzilla::DB;
34 use Bugzilla::Template;
35 use Bugzilla::User;
36
37 my $_template;
38 sub template {
39     my $class = shift;
40     $_template ||= Bugzilla::Template->create();
41     return $_template;
42 }
43
44 my $_cgi;
45 sub cgi {
46     my $class = shift;
47     $_cgi ||= new Bugzilla::CGI();
48     return $_cgi;
49 }
50
51 my $_user;
52 sub user {
53     my $class = shift;
54
55     if (not defined $_user) {
56         $_user = new Bugzilla::User;
57     }
58
59     return $_user;
60 }
61
62 sub login {
63     my ($class, $type) = @_;
64     $_user = Bugzilla::Auth::Login::WWW->login($type);
65 }
66
67 sub logout {
68     my ($class, $option) = @_;
69
70     # If we're not logged in, go away
71     return unless user->id;
72
73     $option = LOGOUT_CURRENT unless defined $option;
74     Bugzilla::Auth::Login::WWW->logout($_user, $option);
75 }
76
77 sub logout_user {
78     my ($class, $user) = @_;
79     # When we're logging out another user we leave cookies alone, and
80     # therefore avoid calling Bugzilla->logout() directly.
81     Bugzilla::Auth::Login::WWW->logout($user, LOGOUT_ALL);
82 }
83
84 # just a compatibility front-end to logout_user that gets a user by id
85 sub logout_user_by_id {
86     my ($class, $id) = @_;
87     my $user = new Bugzilla::User($id);
88     $class->logout_user($user);
89 }
90
91 # hack that invalidates credentials for a single request
92 sub logout_request {
93     undef $_user;
94     # XXX clean this up eventually
95     $::userid = 0;
96     # We can't delete from $cgi->cookie, so logincookie data will remain
97     # there. Don't rely on it: use Bugzilla->user->login instead!
98 }
99
100 my $_dbh;
101 my $_dbh_main;
102 my $_dbh_shadow;
103 sub dbh {
104     my $class = shift;
105
106     # If we're not connected, then we must want the main db
107     if (!$_dbh) {
108         $_dbh = $_dbh_main = Bugzilla::DB::connect_main();
109     }
110
111     return $_dbh;
112 }
113
114 my $_batch;
115 sub batch {
116     my $class = shift;
117     my $newval = shift;
118     if ($newval) {
119         $_batch = $newval;
120     }
121     return $_batch || 0;
122 }
123
124 sub dbwritesallowed {
125     my $class = shift;
126
127     # We can write if we are connected to the main database.
128     # Note that if we don't have a shadowdb, then we claim that its ok
129     # to write even if we're nominally connected to the shadowdb.
130     # This is OK because this method is only used to test if misc
131     # updates can be done, rather than anything complicated.
132     return $class->dbh == $_dbh_main;
133 }
134
135 sub switch_to_shadow_db {
136     my $class = shift;
137
138     if (!$_dbh_shadow) {
139         if (Param('shadowdb')) {
140             $_dbh_shadow = Bugzilla::DB::connect_shadow();
141         } else {
142             $_dbh_shadow = $_dbh_main;
143         }
144     }
145
146     $_dbh = $_dbh_shadow;
147     # we have to return $class->dbh instead of $_dbh as
148     # $_dbh_shadow may be undefined if no shadow DB is used
149     # and no connection to the main DB has been established yet.
150     return $class->dbh;
151 }
152
153 sub switch_to_main_db {
154     my $class = shift;
155
156     $_dbh = $_dbh_main;
157     # We have to return $class->dbh instead of $_dbh as
158     # $_dbh_main may be undefined if no connection to the main DB
159     # has been established yet.
160     return $class->dbh;
161 }
162
163 # Private methods
164
165 # Per process cleanup
166 sub _cleanup {
167     undef $_cgi;
168     undef $_user;
169
170     # See bug 192531. If we don't clear the possibly active statement handles,
171     # then when this is called from the END block, it happens _before_ the
172     # destructors in Bugzilla::DB have happened.
173     # See http://rt.perl.org/rt2/Ticket/Display.html?id=17450#38810
174     # Without disconnecting explicitly here, noone notices, because DBI::END
175     # ends up calling DBD::mysql's $drh->disconnect_all, which is a noop.
176     # This code is evil, but it needs to be done, at least until SendSQL and
177     # friends can be removed
178     @Bugzilla::DB::SQLStateStack = ();
179     undef $Bugzilla::DB::_current_sth;
180
181     # When we support transactions, need to ->rollback here
182     $_dbh_main->disconnect if $_dbh_main;
183     $_dbh_shadow->disconnect if $_dbh_shadow and Param("shadowdb");
184     undef $_dbh_main;
185     undef $_dbh_shadow;
186     undef $_dbh;
187 }
188
189 sub END {
190     _cleanup();
191 }
192
193 1;
194
195 __END__
196
197 =head1 NAME
198
199 Bugzilla - Semi-persistent collection of various objects used by scripts
200 and modules
201
202 =head1 SYNOPSIS
203
204   use Bugzilla;
205
206   sub someModulesSub {
207     Bugzilla->dbh->prepare(...);
208     Bugzilla->template->process(...);
209   }
210
211 =head1 DESCRIPTION
212
213 Several Bugzilla 'things' are used by a variety of modules and scripts. This
214 includes database handles, template objects, and so on.
215
216 This module is a singleton intended as a central place to store these objects.
217 This approach has several advantages:
218
219 =over 4
220
221 =item *
222
223 They're not global variables, so we don't have issues with them staying arround
224 with mod_perl
225
226 =item *
227
228 Everything is in one central place, so its easy to access, modify, and maintain
229
230 =item *
231
232 Code in modules can get access to these objects without having to have them
233 all passed from the caller, and the caller's caller, and....
234
235 =item *
236
237 We can reuse objects across requests using mod_perl where appropriate (eg
238 templates), whilst destroying those which are only valid for a single request
239 (such as the current user)
240
241 =back
242
243 Note that items accessible via this object are demand-loaded when requested.
244
245 For something to be added to this object, it should either be able to benefit
246 from persistence when run under mod_perl (such as the a C<template> object),
247 or should be something which is globally required by a large ammount of code
248 (such as the current C<user> object).
249
250 =head1 METHODS
251
252 Note that all C<Bugzilla> functionality is method based; use C<Bugzilla-E<gt>dbh>
253 rather than C<Bugzilla::dbh>. Nothing cares about this now, but don't rely on
254 that.
255
256 =over 4
257
258 =item C<template>
259
260 The current C<Template> object, to be used for output
261
262 =item C<cgi>
263
264 The current C<cgi> object. Note that modules should B<not> be using this in
265 general. Not all Bugzilla actions are cgi requests. Its useful as a convenience
266 method for those scripts/templates which are only use via CGI, though.
267
268 =item C<user>
269
270 The current C<Bugzilla::User>. C<undef> if there is no currently logged in user
271 or if the login code has not yet been run.
272
273 =item C<login>
274
275 Logs in a user, returning a C<Bugzilla::User> object, or C<undef> if there is
276 no logged in user. See L<Bugzilla::Auth|Bugzilla::Auth>, and
277 L<Bugzilla::User|Bugzilla::User>.
278
279 =item C<logout($option)>
280
281 Logs out the current user, which involves invalidating user sessions and
282 cookies. Three options are available from
283 L<Bugzilla::Constants|Bugzilla::Constants>: LOGOUT_CURRENT (the
284 default), LOGOUT_ALL or LOGOUT_KEEP_CURRENT.
285
286 =item C<logout_user($user)>
287
288 Logs out the specified user (invalidating all his sessions), taking a
289 Bugzilla::User instance.
290
291 =item C<logout_by_id($id)>
292
293 Logs out the user with the id specified. This is a compatibility
294 function to be used in callsites where there is only a userid and no
295 Bugzilla::User instance.
296
297 =item C<logout_request>
298
299 Essentially, causes calls to C<Bugzilla-E<gt>user> to return C<undef>. This has the
300 effect of logging out a user for the current request only; cookies and
301 database sessions are left intact.
302
303 =item C<batch>
304
305 Set to true, by calling Bugzilla->batch(1), to indicate that Bugzilla is
306 being called in a non-interactive manner and errors should be passed to 
307 die() rather than being sent to a browser and finished with an exit().
308 Bugzilla->batch will return the current state of this flag.
309
310 =item C<dbh>
311
312 The current database handle. See L<DBI>.
313
314 =item C<dbwritesallowed>
315
316 Determines if writes to the database are permitted. This is usually used to
317 determine if some general cleanup needs to occur (such as clearing the token
318 table)
319
320 =item C<switch_to_shadow_db>
321
322 Switch from using the main database to using the shadow database.
323
324 =item C<switch_to_main_db>
325
326 Change the database object to refer to the main database.
327
328 =back