rt/lib/RT/Link_Overlay.pm

   1 # {{{ BEGIN BPS TAGGED BLOCK
   2 #
   3 # COPYRIGHT:
   4 #
   5 # This software is Copyright (c) 1996-2004 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 =head1 NAME
  47
  48   RT::Link - an RT Link object
  49
  50 =head1 SYNOPSIS
  51
  52   use RT::Link;
  53
  54 =head1 DESCRIPTION
  55
  56 This module should never be called directly by client code. it's an internal module which
  57 should only be accessed through exported APIs in Ticket other similar objects.
  58
  59 =head1 METHODS
  60
  61
  62 =begin testing
  63
  64
  65 use RT::Link;
  66 my $link = RT::Link->new($RT::SystemUser);
  67
  68
  69 ok (ref $link);
  70 ok (UNIVERSAL::isa($link, 'RT::Link'));
  71 ok (UNIVERSAL::isa($link, 'RT::Base'));
  72 ok (UNIVERSAL::isa($link, 'RT::Record'));
  73 ok (UNIVERSAL::isa($link, 'DBIx::SearchBuilder::Record'));
  74
  75 =end testing
  76
  77 =cut
  78
  79 use strict;
  80 no warnings qw(redefine);
  81
  82
  83 use Carp;
  84 use RT::URI;
  85
  86
  87 # {{{ sub Create
  88
  89 =head2 Create PARAMHASH
  90
  91 Create a new link object. Takes 'Base', 'Target' and 'Type'.
  92 Returns undef on failure or a Link Id on success.
  93
  94 =cut
  95
  96 sub Create {
  97     my $self = shift;
  98     my %args = ( Base   => undef,
  99                  Target => undef,
 100                  Type   => undef,
 101                  @_ );
 102
 103     my $base = RT::URI->new( $self->CurrentUser );
 104     $base->FromURI( $args{'Base'} );
 105
 106     unless ( $base->Resolver and $base->Scheme ) {
 107         $RT::Logger->warning( "$self couldn't resolve base:'"
 108                               . $args{'Base'} . " - "
 109                               . "' into a URI\n" );
 110
 111         return (undef);
 112     }
 113
 114     my $target = RT::URI->new( $self->CurrentUser );
 115     $target->FromURI( $args{'Target'} );
 116
 117     unless ( $target->Resolver ) {
 118         $RT::Logger->warning( "$self couldn't resolve target:'"
 119                               . $args{'Target'} . " - "
 120                               . "' into a URI\n" );
 121
 122         return (undef);
 123     }
 124
 125     my $base_id   = 0;
 126     my $target_id = 0;
 127
 128
 129
 130
 131     if ( $base->IsLocal ) {
 132         unless (UNIVERSAL::can($base->Object, 'Id')) {
 133             return (undef, $self->loc("[_1] appears to be a local object, but can't be found in the database", $args{'Base'}));
 134
 135         }
 136         $base_id = $base->Object->Id;
 137     }
 138     if ( $target->IsLocal ) {
 139         unless (UNIVERSAL::can($target->Object, 'Id')) {
 140             return (undef, $self->loc("[_1] appears to be a local object, but can't be found in the database", $args{'Target'}));
 141
 142         }
 143         $target_id = $target->Object->Id;
 144     }
 145
 146     # {{{ We don't want references to ourself
 147     if ( $base->URI eq $target->URI ) {
 148         return ( 0, $self->loc("Can't link a ticket to itself") );
 149     }
 150
 151     # }}}
 152
 153     my ( $id, $msg ) = $self->SUPER::Create( Base        => $base->URI,
 154                                              Target      => $target->URI,
 155                                              LocalBase   => $base_id,
 156                                              LocalTarget => $target_id,
 157                                              Type        => $args{'Type'} );
 158     return ( $id, $msg );
 159 }
 160
 161 # }}}
 162  # {{{ sub LoadByParams
 163
 164 =head2 LoadByParams
 165
 166   Load an RT::Link object from the database.  Takes three parameters
 167
 168   Base => undef,
 169   Target => undef,
 170   Type =>undef
 171
 172   Base and Target are expected to be integers which refer to Tickets or URIs
 173   Type is the link type
 174
 175 =cut
 176
 177 sub LoadByParams {
 178     my $self = shift;
 179     my %args = ( Base   => undef,
 180                  Target => undef,
 181                  Type   => undef,
 182                  @_ );
 183
 184     my $base = RT::URI->new($self->CurrentUser);
 185     $base->FromURI( $args{'Base'} );
 186
 187     my $target = RT::URI->new($self->CurrentUser);
 188     $target->FromURI( $args{'Target'} );
 189
 190     unless ($base->Resolver && $target->Resolver) {
 191         return ( 0, $self->loc("Couldn't load link") );
 192     }
 193
 194
 195     my ( $id, $msg ) = $self->LoadByCols( Base   => $base->URI,
 196                                           Type   => $args{'Type'},
 197                                           Target => $target->URI );
 198
 199     unless ($id) {
 200         return ( 0, $self->loc("Couldn't load link") );
 201     }
 202 }
 203
 204 # }}}
 205 # {{{ sub Load
 206
 207 =head2 Load
 208
 209   Load an RT::Link object from the database.  Takes one parameter, the id of an entry in the links table.
 210
 211
 212 =cut
 213
 214 sub Load {
 215     my $self       = shift;
 216     my $identifier = shift;
 217
 218
 219
 220
 221     if ( $identifier !~ /^\d+$/ ) {
 222         return ( 0, $self->loc("That's not a numerical id") );
 223     }
 224     else {
 225         my ( $id, $msg ) = $self->LoadById($identifier);
 226         unless ( $self->Id ) {
 227             return ( 0, $self->loc("Couldn't load link") );
 228         }
 229         return ( $id, $msg );
 230     }
 231 }
 232
 233 # }}}
 234
 235
 236 # {{{ TargetURI
 237
 238 =head2 TargetURI
 239
 240 returns an RT::URI object for the "Target" of this link.
 241
 242 =cut
 243
 244 sub TargetURI {
 245     my $self = shift;
 246     my $URI = RT::URI->new($self->CurrentUser);
 247     $URI->FromURI($self->Target);
 248     return ($URI);
 249 }
 250
 251 # }}}
 252 # {{{ sub TargetObj
 253
 254 =head2 TargetObj
 255
 256 =cut
 257
 258 sub TargetObj {
 259   my $self = shift;
 260    return $self->TargetURI->Object;
 261 }
 262 # }}}
 263
 264 # {{{ BaseURI
 265
 266 =head2 BaseURI
 267
 268 returns an RT::URI object for the "Base" of this link.
 269
 270 =cut
 271
 272 sub BaseURI {
 273     my $self = shift;
 274     my $URI = RT::URI->new($self->CurrentUser);
 275     $URI->FromURI($self->Base);
 276     return ($URI);
 277 }
 278
 279 # }}}
 280 # {{{ sub BaseObj
 281
 282 =head2 BaseObj
 283
 284 =cut
 285
 286 sub BaseObj {
 287   my $self = shift;
 288   return $self->BaseURI->Object;
 289 }
 290 # }}}
 291
 292
 293
 294 # Static methods:
 295
 296 # {{{ sub BaseIsLocal
 297
 298 =head2 BaseIsLocal
 299
 300 Returns true if the base of this link is a local ticket
 301
 302 =cut
 303
 304 sub BaseIsLocal {
 305   my $self = shift;
 306   $RT::Logger->crit("Link::BaseIsLocal is deprecated in favor of Link->BaseURI->IsLocal");
 307   return $self->BaseURI->IsLocal;
 308 }
 309
 310 # }}}
 311
 312 # {{{ sub TargetIsLocal
 313
 314 =head2 TargetIsLocal
 315
 316 Returns true if the target of this link is a local ticket
 317
 318 =cut
 319
 320 sub TargetIsLocal {
 321   my $self = shift;
 322   $RT::Logger->crit("Link::BaseIsLocal is deprecated in favor of Link->BaseURI->IsLocal");
 323   return $self->TargetURI->IsLocal;
 324 }
 325
 326 # }}}
 327
 328
 329 # {{{ sub BaseAsHREF
 330
 331 =head2 BaseAsHREF
 332
 333 Returns an HTTP url to access the base of this link
 334
 335 =cut
 336
 337 sub BaseAsHREF {
 338   my $self = shift;
 339   $RT::Logger->crit("Link::BaseAsHREF deprecated in favor of ->BaseURI->AsHREF");
 340   return $self->BaseURI->HREF;
 341 }
 342 # }}}
 343
 344 # {{{ sub TargetAsHREF
 345
 346 =head2 TargetAsHREF
 347
 348 return an HTTP url to access the target of this link
 349
 350 =cut
 351
 352 sub TargetAsHREF {
 353   my $self = shift;
 354   $RT::Logger->crit("Link::TargetAsHREF deprecated in favor of ->TargetURI->AsHREF");
 355   return $self->TargetURI->HREF;
 356 }
 357 # }}}
 358
 359 # {{{ sub AsHREF - Converts Link URIs to HTTP URLs
 360
 361 =head2 URI
 362
 363 Takes a URI and returns an http: url to access that object.
 364
 365 =cut
 366
 367
 368 sub AsHREF {
 369     my $self=shift;
 370
 371     $RT::Logger->crit("AsHREF is gone. look at URI::HREF to figure out what to do with \$URI");
 372 }
 373
 374 # }}}
 375
 376 1;
 377