| 1 | # ===================================================================== | ||
| 2 | # Copyright (c) 2002,2003 IBM Corporation | ||
| 3 | # All rights reserved. This program and the accompanying materials | ||
| 4 | # are made available under the terms of the Common Public License v1.0 | ||
| 5 | # which accompanies this distribution, and is available at | ||
| 6 | # http://www.opensource.org/licenses/cpl.php | ||
| 7 | # | ||
| 8 | # ===================================================================== | ||
| 9 | use Error qw(:try); | ||
| 10 | |||
| 11 | package LS; | ||
| 12 | |||
| 13 | use 5.006; | ||
| 14 | use strict; | ||
| 15 | use warnings; | ||
| 16 | |||
| 17 | our $VERSION = '1.1.7'; | ||
| 18 | |||
| 19 | =head1 NAME | ||
| 20 | |||
| 21 | LS - Perl module for building clients and servers which resolve and perform | ||
| 22 | metadata queries on LSIDs. | ||
| 23 | |||
| 24 | =head1 SYNOPSIS | ||
| 25 | |||
| 26 | use LS::ID; | ||
| 27 | use LS::Locator; | ||
| 28 | |||
| 29 | $lsid = LS::ID->new( | ||
| 30 | 'urn:lsid:biomoby.org:servicetype:Retrieval:2001-09-21T16-00-00Z' | ||
| 31 | ); | ||
| 32 | |||
| 33 | $locator = LS::Locator->new(); | ||
| 34 | $authority = $locator->resolveAuthority($lsid); | ||
| 35 | |||
| 36 | $resource = $authority->getResource($lsid); | ||
| 37 | |||
| 38 | $data = $resource->getData(); | ||
| 39 | |||
| 40 | $response = $data->response(); | ||
| 41 | |||
| 42 | # $response is a filehandle, so you can use it as with any other | ||
| 43 | |||
| 44 | print <$response>; | ||
| 45 | |||
| 46 | |||
| 47 | =head1 DESCRIPTION | ||
| 48 | |||
| 49 | The LS module is used for building clients and servers which resolve LSIDs | ||
| 50 | and perform metadata queries on LSIDs. More information on LSIDs can be | ||
| 51 | found at L<http://www.omg.org/cgi-bin/doc?dtc/04-05-01> | ||
| 52 | |||
| 53 | |||
| 54 | =head2 makeAccessorMethods( $methodList, $package ) | ||
| 55 | |||
| 56 | Creates default accessor methods for an array ref of method names | ||
| 57 | in the package specified by $package | ||
| 58 | |||
| 59 | =cut | ||
| 60 | |||
| 61 | sub makeAccessorMethods { | ||
| 62 | |||
| 63 | my $methodList = shift; | ||
| 64 | my $package = shift; | ||
| 65 | |||
| 66 | unless(UNIVERSAL::isa($methodList, 'ARRAY')) { | ||
| 67 | |||
| 68 | return undef; | ||
| 69 | } | ||
| 70 | |||
| 71 | unless($package) { | ||
| 72 | |||
| 73 | return undef; | ||
| 74 | } | ||
| 75 | |||
| 76 | # | ||
| 77 | # Create the accessor / mutator methods for the bindings class | ||
| 78 | # | ||
| 79 | for my $field (@{ $methodList }) { | ||
| 80 | |||
| 81 | no strict "refs"; | ||
| 82 | |||
| 83 | my $slot = "${package}__${field}"; | ||
| 84 | my $fn = "${package}::${field}"; | ||
| 85 | |||
| 86 | *$fn= sub { | ||
| 87 | |||
| 88 | my $self = shift; | ||
| 89 | |||
| 90 | @_ ? $self->{ $slot } = $_[0] : return $self->{ $slot }; | ||
| 91 | } | ||
| 92 | } | ||
| 93 | } | ||
| 94 | |||
| 95 | =head1 SEE ALSO | ||
| 96 | |||
| 97 | L<LS::ID>, L<LS::Locator>, L<LS::Authority>, L<LS::Resource>, L<LS::Service>, L<LS::SOAP::Service>, L<LS::HTTP::Service>, | ||
| 98 | L<http://www.omg.org/cgi-bin/doc?dtc/04-05-01>, L<http://oss.software.ibm.com/developerworks/projects/lsid> | ||
| 99 | |||
| 100 | =head1 AUTHOR | ||
| 101 | |||
| 102 | IBM | ||
| 103 | |||
| 104 | =head1 COPYRIGHT AND LICENSE | ||
| 105 | |||
| 106 | Copyright (c) 2002,2003 IBM Corporation | ||
| 107 | All rights reserved. This program and the accompanying materials | ||
| 108 | are made available under the terms of the Common Public License v1.0 | ||
| 109 | which accompanies this distribution, and is available at | ||
| 110 | http://www.opensource.org/licenses/cpl.php | ||
| 111 | |||
| 112 | =cut | ||
| 113 | |||
| 114 | package LS::Base; | ||
| 115 | |||
| 116 | use strict; | ||
| 117 | use warnings; | ||
| 118 | |||
| 119 | use vars qw( $_ERR $_STACK_TRACE ); | ||
| 120 | |||
| 121 | use Carp qw(:DEFAULT); | ||
| 122 | |||
| 123 | |||
| 124 | =head1 NAME | ||
| 125 | |||
| 126 | LS::Base - This package is the base package that all other LS packages inherit from. | ||
| 127 | |||
| 128 | =head1 VARIABLES | ||
| 129 | |||
| 130 | A list of variables used in this package. | ||
| 131 | |||
| 132 | =head2 $_ERR | ||
| 133 | |||
| 134 | Package error string. | ||
| 135 | |||
| 136 | =cut | ||
| 137 | |||
| 138 | $_ERR = ''; | ||
| 139 | |||
| 140 | =head2 $_STACK_TRACE | ||
| 141 | |||
| 142 | Holds the Carp stack traces | ||
| 143 | |||
| 144 | =cut | ||
| 145 | |||
| 146 | $_STACK_TRACE = []; | ||
| 147 | |||
| 148 | =head2 appendError( $extraMessage ) | ||
| 149 | |||
| 150 | Appends additional information to the error string | ||
| 151 | Parameters - $extraMessage, Required. The additional information to store. | ||
| 152 | |||
| 153 | =cut | ||
| 154 | |||
| 155 | sub appendError { | ||
| 156 | |||
| 157 | my ($self, $error) = @_; | ||
| 158 | |||
| 159 | if($self && ref $self) { | ||
| 160 | |||
| 161 | $self->{'_err'} .= "\n -> $error"; | ||
| 162 | } | ||
| 163 | else { | ||
| 164 | |||
| 165 | $_ERR .= "\n -> $error"; | ||
| 166 | } | ||
| 167 | } | ||
| 168 | |||
| 169 | |||
| 170 | =head2 recordError( $errorMessage ) - Records the message in the class's error string | ||
| 171 | |||
| 172 | Parameters - $errorMessage, Required. The message to be stored in the class's | ||
| 173 | rror string. | ||
| 174 | |||
| 175 | =cut | ||
| 176 | |||
| 177 | sub recordError { | ||
| 178 | |||
| 179 | my ($self, $error) = @_; | ||
| 180 | |||
| 181 | if($self && ref $self) { | ||
| 182 | |||
| 183 | $self->{'_err'} = $error; | ||
| 184 | } | ||
| 185 | else { | ||
| 186 | |||
| 187 | $_ERR = $error; | ||
| 188 | } | ||
| 189 | } | ||
| 190 | |||
| 191 | =head2 addStackTrace( ) | ||
| 192 | |||
| 193 | Appends a Carp stack trace to the error string | ||
| 194 | |||
| 195 | =cut | ||
| 196 | |||
| 197 | sub addStackTrace { | ||
| 198 | |||
| 199 | my $self = shift; | ||
| 200 | my $previousTraces = shift; | ||
| 201 | |||
| 202 | if($self && ref $self) { | ||
| 203 | |||
| 204 | # Initialize the stack traces on the first call | ||
| 205 | $self->{'_stack_trace'} = [] unless(UNIVERSAL::isa($self->{'_stack_trace'}, 'ARRAY')); | ||
| 206 | |||
| 207 | # Copy an applicable stack traces in before adding our own | ||
| 208 | @{ $self->{'_stack_trace'} } = @{ $previousTraces } if( ref $previousTraces eq 'ARRAY'); | ||
| 209 | |||
| 210 | push @{ $self->{'_stack_trace'} }, Carp::longmess('Stack trace'); | ||
| 211 | } | ||
| 212 | else { | ||
| 213 | |||
| 214 | # Copy an applicable stack traces in before adding our own | ||
| 215 | @{ $_STACK_TRACE } = @{ $previousTraces } if( ref $previousTraces eq 'ARRAY'); | ||
| 216 | |||
| 217 | push @{ $_STACK_TRACE }, Carp::longmess('Stack trace'); | ||
| 218 | } | ||
| 219 | } | ||
| 220 | |||
| 221 | =head2 getStackTrace( ) | ||
| 222 | |||
| 223 | Retrieves a copy (in the form of an arrayref) of the | ||
| 224 | stack traces associated with this object. | ||
| 225 | |||
| 226 | Returns - An arrayref that is a COPY of the arrayref containing | ||
| 227 | all of the stack traces. | ||
| 228 | |||
| 229 | =cut | ||
| 230 | |||
| 231 | sub getStackTrace { | ||
| 232 | |||
| 233 | my $self = shift; | ||
| 234 | |||
| 235 | my $copy = []; | ||
| 236 | |||
| 237 | foreach my $st (@{ $self->{'_stack_trace'} }) { | ||
| 238 | |||
| 239 | push @{ $copy }, $st; | ||
| 240 | } | ||
| 241 | |||
| 242 | # Eh, there won't be that many of them | ||
| 243 | @{ $copy } = reverse( @{ $copy } ); | ||
| 244 | |||
| 245 | return $copy; | ||
| 246 | } | ||
| 247 | |||
| 248 | |||
| 249 | =head2 hasStackTrace( ) | ||
| 250 | |||
| 251 | Determins whether or not a stack trace is present | ||
| 252 | |||
| 253 | Returns - True if there is a stack trace | ||
| 254 | False / undef if no stack trace is available | ||
| 255 | =cut | ||
| 256 | |||
| 257 | sub hasStackTrace { | ||
| 258 | |||
| 259 | my $self = shift; | ||
| 260 | |||
| 261 | if($self && ref $self) { | ||
| 262 | |||
| 263 | return (scalar(@{ $self->{'_stack_trace'} } > 0) ); | ||
| 264 | } | ||
| 265 | else { | ||
| 266 | |||
| 267 | return (scalar(@{ $_STACK_TRACE }) > 0); | ||
| 268 | } | ||
| 269 | } | ||
| 270 | |||
| 271 | |||
| 272 | =head2 clearStackTrace( ) | ||
| 273 | |||
| 274 | Clears the stack trace | ||
| 275 | |||
| 276 | =cut | ||
| 277 | |||
| 278 | sub clearStackTrace { | ||
| 279 | |||
| 280 | my $self = shift; | ||
| 281 | |||
| 282 | if($self && ref $self) { | ||
| 283 | |||
| 284 | $self->{'_stack_trace'} = []; | ||
| 285 | } | ||
| 286 | else { | ||
| 287 | |||
| 288 | $_STACK_TRACE = []; | ||
| 289 | } | ||
| 290 | } | ||
| 291 | |||
| 292 | |||
| 293 | =head2 errorString( ) | ||
| 294 | |||
| 295 | Returns one of two error strings: | ||
| 296 | |||
| 297 | 1. if the class has been blessed in to a reference, the internal | ||
| 298 | class error string is returned. | ||
| 299 | 2. if the class has not been blessed in to a reference, the package | ||
| 300 | error string is returned. | ||
| 301 | |||
| 302 | These values may be undef if no error has occured. | ||
| 303 | |||
| 304 | =cut | ||
| 305 | |||
| 306 | sub errorString { | ||
| 307 | |||
| 308 | my $self = shift; | ||
| 309 | |||
| 310 | if ($self && ref $self) { | ||
| 311 | |||
| 312 | return $self->{'_err'}; | ||
| 313 | } | ||
| 314 | |||
| 315 | return $_ERR; | ||
| 316 | } | ||
| 317 | |||
| 318 | |||
| 319 | =head2 error_string( ) | ||
| 320 | |||
| 321 | Synonym for errorString | ||
| 322 | |||
| 323 | =cut | ||
| 324 | |||
| 325 | sub error_string { | ||
| 326 | |||
| 327 | my $self = shift; | ||
| 328 | return $self->errorString(); | ||
| 329 | } | ||
| 330 | |||
| 331 | |||
| 332 | =head2 errorDetails( ) | ||
| 333 | |||
| 334 | Returns the complete error with all applicable | ||
| 335 | stack traces. | ||
| 336 | |||
| 337 | Returns - A very detailed error message | ||
| 338 | |||
| 339 | =cut | ||
| 340 | |||
| 341 | sub errorDetails { | ||
| 342 | |||
| 343 | my $self = shift; | ||
| 344 | |||
| 345 | my $errorMessage; | ||
| 346 | |||
| 347 | if ($self && ref $self) { | ||
| 348 | |||
| 349 | $errorMessage = $self->{'_err'}; | ||
| 350 | |||
| 351 | foreach my $st (@{ $self->{'_stack_trace'} }) { | ||
| 352 | |||
| 353 | $errorMessage .= "\n\n" . $st; | ||
| 354 | } | ||
| 355 | |||
| 356 | return $errorMessage; | ||
| 357 | } | ||
| 358 | |||
| 359 | $errorMessage = $_ERR; | ||
| 360 | |||
| 361 | foreach my $st (@{ $self->{'_stack_trace'} }) { | ||
| 362 | |||
| 363 | $errorMessage .= "\n\n" . $st; | ||
| 364 | } | ||
| 365 | |||
| 366 | return $errorMessage; | ||
| 367 | } | ||
| 368 | |||
| 369 | =head1 SEE ALSO | ||
| 370 | |||
| 371 | L<LS::ID>, L<LS::Locator>, L<LS::Authority>, L<LS::Resource>, L<LS::Service>, L<LS::SOAP::Service>, L<LS::HTTP::Service>, | ||
| 372 | L<http://www.omg.org/cgi-bin/doc?dtc/04-05-01>, L<http://oss.software.ibm.com/developerworks/projects/lsid> | ||
| 373 | |||
| 374 | =head1 AUTHOR | ||
| 375 | |||
| 376 | IBM | ||
| 377 | |||
| 378 | =head1 COPYRIGHT AND LICENSE | ||
| 379 | |||
| 380 | Copyright (c) 2002,2003 IBM Corporation | ||
| 381 | All rights reserved. This program and the accompanying materials | ||
| 382 | are made available under the terms of the Common Public License v1.0 | ||
| 383 | which accompanies this distribution, and is available at | ||
| 384 | http://www.opensource.org/licenses/cpl.php | ||
| 385 | |||
| 386 | =cut | ||
| 387 | |||
| 388 | package LS::Exception; | ||
| 389 | |||
| 390 | use strict; | ||
| 391 | use warnings; | ||
| 392 | |||
| 393 | use base 'Error'; | ||
| 394 | use overload ('""' => 'stringify'); | ||
| 395 | |||
| 396 | |||
| 397 | sub new | ||
| 398 | { | ||
| 399 | my $self = shift; | ||
| 400 | |||
| 401 | my $text = shift; | ||
| 402 | my $object = shift; | ||
| 403 | |||
| 404 | local $Error::Depth = $Error::Depth + 1; | ||
| 405 | local $Error::Debug = 1; | ||
| 406 | |||
| 407 | return $self->SUPER::new(-text=> ($text || ""), -object=> $object); | ||
| 408 | } | ||
| 409 | |||
| 410 | |||
| 411 | package LS::InvalidParameterException; | ||
| 412 | use base 'LS::Exception'; | ||
| 413 | |||
| 414 | package LS::MalformedParameterException; | ||
| 415 | use base 'LS::Exception'; | ||
| 416 | |||
| 417 | package LS::RuntimeException; | ||
| 418 | use base 'LS::Exception'; | ||
| 419 | |||
| 420 | package LS::ClientException; | ||
| 421 | use base 'LS::Exception'; | ||
| 422 | |||
| 423 | 1; | ||
| 424 | |||
| 425 | __END__ |