lib/Clearquest/Admin.pm

   1 =pod
   2
   3 =head1 NAME $RCSfile: Admin.pm,v $
   4
   5 Clearquest Admin - Provide access Clearquest AdminSession objects
   6
   7 =head1 VERSION
   8
   9 =over
  10
  11 =item Author
  12
  13 Andrew DeFaria <Andrew@ClearSCM.com>
  14
  15 =item Revision
  16
  17 $Revision: 1.3 $
  18
  19 =item Created
  20
  21 Wed Apr 18 09:59:47 PDT 2012
  22
  23 =item Modified
  24
  25 $Date: 2012/11/09 06:53:11 $
  26
  27 =back
  28
  29 =head1 SYNOPSIS
  30
  31 Provides an interface to the Clearquest AdminSession objects. These are for
  32 dealing with objects in the schema, not the user database.
  33
  34 =head1 DESCRIPTION
  35
  36 The Admin object allows you to create a session object associated with a schema
  37 repository. This allows you to retrieve and modify information in a schema
  38 repository. You must log into the Admin object as an admin user.
  39
  40 Functions are available to deal with users, groups, databases and schemas.
  41
  42 Note: Admin object needs to be filled out with more functions over time...
  43
  44 =head1 ROUTINES
  45
  46 The following methods are available:
  47
  48 =cut
  49
  50 package Clearquest::Admin;
  51
  52 use strict;
  53 use warnings;
  54
  55 use Carp;
  56 use File::Basename;
  57 use FindBin;
  58
  59 use DateUtils;
  60 use Display;
  61 use GetConfig;
  62
  63 use Clearquest;
  64
  65 # Seed options from config file
  66 my $config = $ENV{CQD_CONF} || dirname (__FILE__) . '/../../etc/cqdservice.conf';
  67
  68 croak "Unable to find config file $config" unless -r $config;
  69
  70 our %OPTS = GetConfig $config;
  71
  72 our $VERSION  = '$Revision: 1.3 $';
  73    ($VERSION) = ($VERSION =~ /\$Revision: (.*) /);
  74
  75 # Override options if in the environment
  76 $OPTS{CQD_HOST}          = $ENV{CQD_HOST}
  77   if $ENV{CQD_HOST};
  78 $OPTS{CQD_PORT}          = $ENV{CQD_PORT}
  79   if $ENV{CQD_PORT};
  80 $OPTS{CQD_MULTITHREADED} = $ENV{CQD_MULTITHREADED}
  81   if defined $ENV{CQD_MULTITHREADED};
  82 $OPTS{CQD_DATABASE}      = $ENV{CQD_DATABASE}
  83   if $ENV{CQD_DATABASE};
  84 $OPTS{CQD_USERNAME}      = $ENV{CQD_USERNAME}
  85   if $ENV{CQD_USERNAME};
  86 $OPTS{CQD_PASSWORD}      = $ENV{CQD_PASSWORD}
  87   if $ENV{CQD_PASSWORD};
  88 $OPTS{CQD_DBSET}         = $ENV{CQD_DBSET}
  89   if $ENV{CQD_DBSET};
  90
  91 sub getUser ($) {
  92   my ($self, $loginname) = @_;
  93
  94 =pod
  95
  96 =head2 getUser ($)
  97
  98 Returns a user object for the specified user or undef.
  99
 100 Parameters:
 101
 102 =for html <blockquote>
 103
 104 =over
 105
 106 =item $username
 107
 108 The $loginname to retrieve the user object for
 109
 110 =back
 111
 112 =for html </blockquote>
 113
 114 Returns:
 115
 116 =for html <blockquote>
 117
 118 =over
 119
 120 =item User object
 121
 122 A user object
 123
 124 =back
 125
 126 =for html </blockquote>
 127
 128 =cut
 129
 130   return $self->{session}->GetUser ($loginname);
 131 } # getNext
 132
 133 sub userActive ($) {
 134   my ($self, $loginname) = @_;
 135
 136 =pod
 137
 138 =head2 userActive ($)
 139
 140 Returns a true if user is active
 141
 142 Parameters:
 143
 144 =for html <blockquote>
 145
 146 =over
 147
 148 =item $username
 149
 150 The $loginname to see if active
 151
 152 =back
 153
 154 =for html </blockquote>
 155
 156 Returns:
 157
 158 =for html <blockquote>
 159
 160 =over
 161
 162 =item 1 if true, 0 if false
 163
 164 =back
 165
 166 =for html </blockquote>
 167
 168 =cut
 169
 170   my $user = $self->getUser ($loginname);
 171
 172   if ($user) {
 173     return $user->GetActive;
 174   } else {
 175     return 0;
 176   } # if
 177 } # userActive
 178
 179 sub userActivate ($) {
 180   my ($self, $loginname) = @_;
 181
 182 =pod
 183
 184 =head2 userActivate ($)
 185
 186 Activates a user if they were inactive
 187
 188 Parameters:
 189
 190 =for html <blockquote>
 191
 192 =over
 193
 194 =item $username
 195
 196 The $loginname to activate
 197
 198 =back
 199
 200 =for html </blockquote>
 201
 202 Returns:
 203
 204 =for html <blockquote>
 205
 206 =over
 207
 208 =item nothing
 209
 210 =back
 211
 212 =for html </blockquote>
 213
 214 =cut
 215
 216   unless ($self->activeUser ($logname)) {
 217     my $user = $self->getUser ($loginname);
 218
 219     if ($user) {
 220       $user->SetUser (1);
 221     } # if
 222   } # unless
 223 } # userActive
 224
 225 sub userActivate ($) {
 226   my ($self, $loginname) = @_;
 227
 228 =pod
 229
 230 =head2 userInactivate ($)
 231
 232 Inactivates a user if they were active
 233
 234 Parameters:
 235
 236 =for html <blockquote>
 237
 238 =over
 239
 240 =item $username
 241
 242 The $loginname to inactivate
 243
 244 =back
 245
 246 =for html </blockquote>
 247
 248 Returns:
 249
 250 =for html <blockquote>
 251
 252 =over
 253
 254 =item nothing
 255
 256 =back
 257
 258 =for html </blockquote>
 259
 260 =cut
 261
 262   if ($self->activeUser ($logname)) {
 263     my $user = $self->getUser ($loginname);
 264
 265     if ($user) {
 266       $user->SetUser (0);
 267     } # if
 268   } # unless
 269 } # userInactive
 270
 271 sub new () {
 272   my ($class, $username, $password, $dbset) = @_;
 273
 274   my $self = bless {}, $class;
 275
 276   if (ref $username eq 'HASH') {
 277     my %parms = %$username;
 278
 279     $self->{username} = $parms{username};
 280     $self->{password} = $parms{password};
 281     $self->{dbset}    = $parms{dbset};
 282   } else {
 283     $self->{username} = $username;
 284     $self->{password} = $password;
 285     $self->{dbset}    = $dbset;
 286   } # if
 287
 288   return $self;
 289 } # new
 290
 291 sub connect (;$$$) {
 292
 293 =pod
 294
 295 =head2 connect (;$$$)
 296
 297 Connect to the Clearquest schema database. You can supply parameters such as
 298 username, password, etc and they will override any passed to
 299 Clearquest::Admin::new (or those coming from ../etc/cq.conf)
 300
 301 Parameters:
 302
 303 =for html <blockquote>
 304
 305 =over
 306
 307 =item $username
 308
 309 Username to use to connect to the schema database
 310
 311 =item $password
 312
 313 Password to use to connect to the schema database
 314
 315 =item $dbset
 316
 317 Database set to connect to (Default: Connect to the default dbset)
 318
 319 =back
 320
 321 =for html </blockquote>
 322
 323 Returns:
 324
 325 =for html <blockquote>
 326
 327 =over
 328
 329 =item 1
 330
 331 =back
 332
 333 =for html </blockquote>
 334
 335 =cut
 336
 337   my ($self, $username, $password, $dbset) = @_;
 338
 339   $self->{username} = $username if $username;
 340   $self->{password} = $password if $password;
 341   $self->{database} = $database if $database;
 342   $self->{dbset}    = $dbset    if $dbset;
 343
 344   $self->{session}  = CQAdminSession::Build;
 345
 346   # TODO: Should handle failures better
 347   $self->{session}->($self->{username},
 348                      $self->{password},
 349                      $self->{dbset});
 350   $self->{loggedin} = 1;
 351
 352   return $self->{loggedin};
 353 } # connect
 354
 355 sub connected () {
 356   my ($self) = @_;
 357
 358 =pod
 359
 360 =head2 connected ()
 361
 362 Returns 1 if we are currently connected to a Clearquest Admin Schema Database
 363
 364 Parameters:
 365
 366 =for html <blockquote>
 367
 368 =over
 369
 370 =item none
 371
 372 =back
 373
 374 =for html </blockquote>
 375
 376 Returns:
 377
 378 =for html <blockquote>
 379
 380 =over
 381
 382 =item 1 if logged in - 0 if not
 383
 384 =back
 385
 386 =for html </blockquote>
 387
 388 =cut
 389
 390   return $self->{loggedin};
 391 } # connected
 392
 393 sub disconnect () {
 394   my ($self) = @_;
 395
 396 =pod
 397
 398 =head2 disconnect ()
 399
 400 Disconnect from Clearquest Admin Schema Database
 401
 402 Parameters:
 403
 404 =for html <blockquote>
 405
 406 =over
 407
 408 =item none
 409
 410 =back
 411
 412 =for html </blockquote>
 413
 414 Returns:
 415
 416 =for html <blockquote>
 417
 418 =over
 419
 420 =item nothing
 421
 422 =back
 423
 424 =for html </blockquote>
 425
 426 =cut
 427
 428   CQAdminSession::Unbuild ($self->{session});
 429
 430   undef $self->{session};
 431
 432   $self->{loggedin} = 0;
 433
 434   return;
 435 } # disconnect
 436
 437
 438
 439 1;
 440
 441 =pod
 442
 443 =head1 CONFIGURATION AND ENVIRONMENT
 444
 445 DEBUG: If set then $debug is set to this level.
 446
 447 VERBOSE: If set then $verbose is set to this level.
 448
 449 TRACE: If set then $trace is set to this level.
 450
 451 =head1 DEPENDENCIES
 452
 453 =head2 Perl Modules
 454
 455 L<Carp>
 456
 457 L<File::Basename|File::Basename>
 458
 459 L<FindBin>
 460
 461 L<IO::Socket|IO::Socket>
 462
 463 L<Net::hostent|Net::hostent>
 464
 465 L<POSIX>
 466
 467 =head2 ClearSCM Perl Modules
 468
 469 =begin man
 470
 471  DateUtils
 472  Display
 473  GetConfig
 474
 475 =end man
 476
 477 =begin html
 478
 479 <blockquote>
 480 <a href="http://clearscm.com/php/scm_man.php?file=lib/DateUtils.pm">DateUtils</a><br>
 481 <a href="http://clearscm.com/php/scm_man.php?file=lib/Display.pm">Display</a><br>
 482 <a href="http://clearscm.com/php/scm_man.php?file=lib/GetConfig.pm">GetConf</a><br>
 483 </blockquote>
 484
 485 =end html
 486
 487 =head1 SEE ALSO
 488
 489 =head1 BUGS AND LIMITATIONS
 490
 491 There are no known bugs in this module.
 492
 493 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
 494
 495 =head1 LICENSE AND COPYRIGHT
 496
 497 Copyright (c) 2011, ClearSCM, Inc. All rights reserved.
 498
 499 =cut