rt/lib/RT/Link_Overlay.pm

   1 # BEGIN BPS TAGGED BLOCK {{{
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2005 Best Practical Solutions, LLC
   6 #                                          <jesse@bestpractical.com>
   7 #
   8 # (Except where explicitly superseded by other copyright notices)
   9 #
  10 #
  11 # LICENSE:
  12 #
  13 # This work is made available to you under the terms of Version 2 of
  14 # the GNU General Public License. A copy of that license should have
  15 # been provided with this software, but in any event can be snarfed
  16 # from www.gnu.org.
  17 #
  18 # This work is distributed in the hope that it will be useful, but
  19 # WITHOUT ANY WARRANTY; without even the implied warranty of
  20 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 # General Public License for more details.
  22 #
  23 # You should have received a copy of the GNU General Public License
  24 # along with this program; if not, write to the Free Software
  25 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  26 #
  27 #
  28 # CONTRIBUTION SUBMISSION POLICY:
  29 #
  30 # (The following paragraph is not intended to limit the rights granted
  31 # to you to modify and distribute this software under the terms of
  32 # the GNU General Public License and is only of importance to you if
  33 # you choose to contribute your changes and enhancements to the
  34 # community by submitting them to Best Practical Solutions, LLC.)
  35 #
  36 # By intentionally submitting any modifications, corrections or
  37 # derivatives to this work, or any other work intended for use with
  38 # Request Tracker, to Best Practical Solutions, LLC, you confirm that
  39 # you are the copyright holder for those contributions and you grant
  40 # Best Practical Solutions,  LLC a nonexclusive, worldwide, irrevocable,
  41 # royalty-free, perpetual, license to use, copy, create derivative
  42 # works based on those contributions, and sublicense and distribute
  43 # those contributions and any derivatives thereof.
  44 #
  45 # END BPS TAGGED BLOCK }}}
  46
  47 =head1 NAME
  48
  49   RT::Link - an RT Link object
  50
  51 =head1 SYNOPSIS
  52
  53   use RT::Link;
  54
  55 =head1 DESCRIPTION
  56
  57 This module should never be called directly by client code. it's an internal module which
  58 should only be accessed through exported APIs in Ticket other similar objects.
  59
  60 =head1 METHODS
  61
  62
  63 =begin testing
  64
  65
  66 use RT::Link;
  67 my $link = RT::Link->new($RT::SystemUser);
  68
  69
  70 ok (ref $link);
  71 ok (UNIVERSAL::isa($link, 'RT::Link'));
  72 ok (UNIVERSAL::isa($link, 'RT::Base'));
  73 ok (UNIVERSAL::isa($link, 'RT::Record'));
  74 ok (UNIVERSAL::isa($link, 'DBIx::SearchBuilder::Record'));
  75
  76 =end testing
  77
  78 =cut
  79
  80
  81 package RT::Link;
  82
  83 use strict;
  84 no warnings qw(redefine);
  85
  86
  87 use Carp;
  88 use RT::URI;
  89
  90
  91 # {{{ sub Create
  92
  93 =head2 Create PARAMHASH
  94
  95 Create a new link object. Takes 'Base', 'Target' and 'Type'.
  96 Returns undef on failure or a Link Id on success.
  97
  98 =cut
  99
 100 sub Create {
 101     my $self = shift;
 102     my %args = ( Base   => undef,
 103                  Target => undef,
 104                  Type   => undef,
 105                  @_ );
 106
 107     my $base = RT::URI->new( $self->CurrentUser );
 108     $base->FromURI( $args{'Base'} );
 109
 110     unless ( $base->Resolver && $base->Scheme ) {
 111         my $msg = $self->loc("Couldn't resolve base '[_1]' into a URI.",
 112                              $args{'Base'});
 113         $RT::Logger->warning( "$self $msg\n" );
 114
 115         if (wantarray) {
 116             return(undef, $msg);
 117         } else {
 118             return (undef);
 119         }
 120     }
 121
 122     my $target = RT::URI->new( $self->CurrentUser );
 123     $target->FromURI( $args{'Target'} );
 124
 125     unless ( $target->Resolver ) {
 126         my $msg = $self->loc("Couldn't resolve target '[_1]' into a URI.",
 127                              $args{'Target'});
 128         $RT::Logger->warning( "$self $msg\n" );
 129
 130         if (wantarray) {
 131             return(undef, $msg);
 132         } else {
 133             return (undef);
 134         }
 135     }
 136
 137     my $base_id   = 0;
 138     my $target_id = 0;
 139
 140
 141
 142
 143     if ( $base->IsLocal ) {
 144         unless (UNIVERSAL::can($base->Object, 'Id')) {
 145             return (undef, $self->loc("[_1] appears to be a local object, but can't be found in the database", $args{'Base'}));
 146
 147         }
 148         $base_id = $base->Object->Id;
 149     }
 150     if ( $target->IsLocal ) {
 151         unless (UNIVERSAL::can($target->Object, 'Id')) {
 152             return (undef, $self->loc("[_1] appears to be a local object, but can't be found in the database", $args{'Target'}));
 153
 154         }
 155         $target_id = $target->Object->Id;
 156     }
 157
 158     # {{{ We don't want references to ourself
 159     if ( $base->URI eq $target->URI ) {
 160         return ( 0, $self->loc("Can't link a ticket to itself") );
 161     }
 162
 163     # }}}
 164
 165     my ( $id, $msg ) = $self->SUPER::Create( Base        => $base->URI,
 166                                              Target      => $target->URI,
 167                                              LocalBase   => $base_id,
 168                                              LocalTarget => $target_id,
 169                                              Type        => $args{'Type'} );
 170     return ( $id, $msg );
 171 }
 172
 173 # }}}
 174  # {{{ sub LoadByParams
 175
 176 =head2 LoadByParams
 177
 178   Load an RT::Link object from the database.  Takes three parameters
 179
 180   Base => undef,
 181   Target => undef,
 182   Type =>undef
 183
 184   Base and Target are expected to be integers which refer to Tickets or URIs
 185   Type is the link type
 186
 187 =cut
 188
 189 sub LoadByParams {
 190     my $self = shift;
 191     my %args = ( Base   => undef,
 192                  Target => undef,
 193                  Type   => undef,
 194                  @_ );
 195
 196     my $base = RT::URI->new($self->CurrentUser);
 197     $base->FromURI( $args{'Base'} );
 198
 199     my $target = RT::URI->new($self->CurrentUser);
 200     $target->FromURI( $args{'Target'} );
 201
 202     unless ($base->Resolver && $target->Resolver) {
 203         return ( 0, $self->loc("Couldn't load link") );
 204     }
 205
 206
 207     my ( $id, $msg ) = $self->LoadByCols( Base   => $base->URI,
 208                                           Type   => $args{'Type'},
 209                                           Target => $target->URI );
 210
 211     unless ($id) {
 212         return ( 0, $self->loc("Couldn't load link") );
 213     }
 214 }
 215
 216 # }}}
 217 # {{{ sub Load
 218
 219 =head2 Load
 220
 221   Load an RT::Link object from the database.  Takes one parameter, the id of an entry in the links table.
 222
 223
 224 =cut
 225
 226 sub Load {
 227     my $self       = shift;
 228     my $identifier = shift;
 229
 230
 231
 232
 233     if ( $identifier !~ /^\d+$/ ) {
 234         return ( 0, $self->loc("That's not a numerical id") );
 235     }
 236     else {
 237         my ( $id, $msg ) = $self->LoadById($identifier);
 238         unless ( $self->Id ) {
 239             return ( 0, $self->loc("Couldn't load link") );
 240         }
 241         return ( $id, $msg );
 242     }
 243 }
 244
 245 # }}}
 246
 247
 248 # {{{ TargetURI
 249
 250 =head2 TargetURI
 251
 252 returns an RT::URI object for the "Target" of this link.
 253
 254 =cut
 255
 256 sub TargetURI {
 257     my $self = shift;
 258     my $URI = RT::URI->new($self->CurrentUser);
 259     $URI->FromURI($self->Target);
 260     return ($URI);
 261 }
 262
 263 # }}}
 264 # {{{ sub TargetObj
 265
 266 =head2 TargetObj
 267
 268 =cut
 269
 270 sub TargetObj {
 271     my $self = shift;
 272     return $self->TargetURI->Object;
 273 }
 274 # }}}
 275
 276 # {{{ BaseURI
 277
 278 =head2 BaseURI
 279
 280 returns an RT::URI object for the "Base" of this link.
 281
 282 =cut
 283
 284 sub BaseURI {
 285     my $self = shift;
 286     my $URI = RT::URI->new($self->CurrentUser);
 287     $URI->FromURI($self->Base);
 288     return ($URI);
 289 }
 290
 291 # }}}
 292 # {{{ sub BaseObj
 293
 294 =head2 BaseObj
 295
 296 =cut
 297
 298 sub BaseObj {
 299   my $self = shift;
 300   return $self->BaseURI->Object;
 301 }
 302 # }}}
 303
 304
 305
 306 # Static methods:
 307
 308 # {{{ sub BaseIsLocal
 309
 310 =head2 BaseIsLocal
 311
 312 Returns true if the base of this link is a local ticket
 313
 314 =cut
 315
 316 sub BaseIsLocal {
 317   my $self = shift;
 318   $RT::Logger->crit("Link::BaseIsLocal is deprecated in favor of Link->BaseURI->IsLocal at (". join(":",caller).")");
 319   return $self->BaseURI->IsLocal;
 320 }
 321
 322 # }}}
 323
 324 # {{{ sub TargetIsLocal
 325
 326 =head2 TargetIsLocal
 327
 328 Returns true if the target of this link is a local ticket
 329
 330 =cut
 331
 332 sub TargetIsLocal {
 333   my $self = shift;
 334   $RT::Logger->crit("Link::BaseIsLocal is deprecated in favor of Link->BaseURI->IsLocal at (". join(":",caller).")");
 335   return $self->TargetURI->IsLocal;
 336 }
 337
 338 # }}}
 339
 340
 341 # {{{ sub BaseAsHREF
 342
 343 =head2 BaseAsHREF
 344
 345 Returns an HTTP url to access the base of this link
 346
 347 =cut
 348
 349 sub BaseAsHREF {
 350   my $self = shift;
 351   $RT::Logger->crit("Link::BaseAsHREF deprecated in favor of ->BaseURI->AsHREF at (". join(":",caller).")");
 352   return $self->BaseURI->HREF;
 353 }
 354 # }}}
 355
 356 # {{{ sub TargetAsHREF
 357
 358 =head2 TargetAsHREF
 359
 360 return an HTTP url to access the target of this link
 361
 362 =cut
 363
 364 sub TargetAsHREF {
 365   my $self = shift;
 366   $RT::Logger->crit("Link::TargetAsHREF deprecated in favor of ->TargetURI->AsHREF at (". join(":",caller).")");
 367   return $self->TargetURI->HREF;
 368 }
 369 # }}}
 370
 371 # {{{ sub AsHREF - Converts Link URIs to HTTP URLs
 372
 373 =head2 URI
 374
 375 Takes a URI and returns an http: url to access that object.
 376
 377 =cut
 378
 379
 380 sub AsHREF {
 381     my $self=shift;
 382
 383     $RT::Logger->crit("AsHREF is gone. look at URI::HREF to figure out what to do with \$URI");
 384 }
 385
 386 # }}}
 387
 388 1;
 389