| 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 | package LS::Authority; | ||
| 10 | |||
| 11 | use strict; | ||
| 12 | use warnings; | ||
| 13 | |||
| 14 | use vars qw($METHOD_PREFIX); | ||
| 15 | |||
| 16 | |||
| 17 | use SOAP::Lite; | ||
| 18 | |||
| 19 | |||
| 20 | use LS::ID; | ||
| 21 | use LS::Authority::WSDL::Constants; | ||
| 22 | |||
| 23 | use LS::Client; | ||
| 24 | use LS::Client::HTTP; | ||
| 25 | use LS::Client::SOAP; | ||
| 26 | |||
| 27 | use LS::Cache::Manager; | ||
| 28 | |||
| 29 | use base 'LS::Client'; | ||
| 30 | |||
| 31 | # | ||
| 32 | # $METHOD_PREFIX - | ||
| 33 | # | ||
| 34 | $METHOD_PREFIX = ''; | ||
| 35 | |||
| 36 | |||
| 37 | |||
| 38 | |||
| 39 | |||
| 40 | # | ||
| 41 | # new( $id ) - Creates a new interface to an LSID's authority based on the LSID | ||
| 42 | # in parameter $id. | ||
| 43 | # | ||
| 44 | # If the authority can not be located or some other error occurs in the | ||
| 45 | # resolution process, the package level error variable will contain any | ||
| 46 | # details available. | ||
| 47 | # | ||
| 48 | # The error message can be retrieved using the errorString method inherited | ||
| 49 | # from LS::Client. | ||
| 50 | # | ||
| 51 | sub new { | ||
| 52 | |||
| 53 | my $class = shift; | ||
| 54 | my ($lsid) = @_; | ||
| 55 | |||
| 56 | # Make sure LS::Locator is loaded | ||
| 57 | require LS::Locator; | ||
| 58 | |||
| 59 | # LS::Locator objects resolve LSIDs using all available methods (file, network, etc.) | ||
| 60 | my $locator = LS::Locator->new(); | ||
| 61 | unless( UNIVERSAL::isa($locator, 'LS::Locator') ) { | ||
| 62 | |||
| 63 | LS::Base->recordError( 'Unable to create LS::Locator object' ); | ||
| 64 | LS::Base->appendError( (LS::Locator->errorString() || 'No error message from LS::Locator') ); | ||
| 65 | |||
| 66 | LS::Base->addStackTrace( LS::Locator->getStackTrace() ); | ||
| 67 | |||
| 68 | return undef; | ||
| 69 | } | ||
| 70 | |||
| 71 | # Use the Locator to resolve the LSID in to an LS::Authority interface | ||
| 72 | my $authority = $locator->resolveAuthority($lsid); | ||
| 73 | unless (UNIVERSAL::isa($authority, 'LS::Authority')) { | ||
| 74 | |||
| 75 | LS::Base->recordError( 'Unable to locate authority ' ); | ||
| 76 | LS::Base->appendError( ($locator->errorString || 'No error message from LS::Locator') ); | ||
| 77 | |||
| 78 | LS::Base->addStackTrace( $locator->getStackTrace() ); | ||
| 79 | |||
| 80 | return undef; | ||
| 81 | } | ||
| 82 | |||
| 83 | return $authority; | ||
| 84 | } | ||
| 85 | |||
| 86 | |||
| 87 | # | ||
| 88 | # new_by_hostname( $host, $port, $path, $username, $password ) | ||
| 89 | # | ||
| 90 | # - Creates a new interface to an LSID authority from the specified host information. | ||
| 91 | # | ||
| 92 | # The authority's credentials will be set to the specified username and password for | ||
| 93 | # subsequent calls to the authority. | ||
| 94 | # | ||
| 95 | sub new_by_hostname { | ||
| 96 | |||
| 97 | my $class = shift; | ||
| 98 | my ($host, $port, $service_path, $username, $password) = @_; | ||
| 99 | |||
| 100 | $class = bless { | ||
| 101 | _host => $host, | ||
| 102 | _port => $port, | ||
| 103 | _path => ($service_path || '/authority/'), | ||
| 104 | _cache=> LS::Cache::Manager->new(), | ||
| 105 | }, $class; | ||
| 106 | |||
| 107 | if($username || $password) { | ||
| 108 | |||
| 109 | $class->credentials( LS::Client::Credentials->new(username=> $username, | ||
| 110 | password=> $password)); | ||
| 111 | } | ||
| 112 | |||
| 113 | return $class; | ||
| 114 | } | ||
| 115 | |||
| 116 | |||
| 117 | # | ||
| 118 | # host - Returns the DNS hostname of the authority | ||
| 119 | # | ||
| 120 | sub host { | ||
| 121 | |||
| 122 | return $_[0]->{'_host'}; | ||
| 123 | } | ||
| 124 | |||
| 125 | |||
| 126 | # | ||
| 127 | # port - Returns the network port of the authority | ||
| 128 | # | ||
| 129 | sub port { | ||
| 130 | |||
| 131 | return $_[0]->{'_port'}; | ||
| 132 | } | ||
| 133 | |||
| 134 | |||
| 135 | # | ||
| 136 | # path - Returns the path to the authority. | ||
| 137 | # | ||
| 138 | # This method takes care to collapse multiple leading | ||
| 139 | # '/' characters in to a single '/' | ||
| 140 | # | ||
| 141 | sub path { | ||
| 142 | |||
| 143 | my $path = $_[0]->{'_path'}; | ||
| 144 | $path =~ s|^/+||; | ||
| 145 | |||
| 146 | return '/' . $path; | ||
| 147 | } | ||
| 148 | |||
| 149 | |||
| 150 | # | ||
| 151 | # authenticate - Deprecated. The credentials method, inherited from LS::Client | ||
| 152 | # should be used instead. | ||
| 153 | # | ||
| 154 | sub authenticate { | ||
| 155 | |||
| 156 | die(__PACKAGE__ . ': This method is deprecated. Use the method LS::Client::Credentials instead.'); | ||
| 157 | |||
| 158 | my $self = shift; | ||
| 159 | my %options = @_; | ||
| 160 | |||
| 161 | $self->{'_credentials'} = LS::Client::Credentials->new(); | ||
| 162 | |||
| 163 | $self->{'_credentials'}->username($options{'username'}); | ||
| 164 | $self->{'_credentials'}->password($options{'password'}); | ||
| 165 | } | ||
| 166 | |||
| 167 | |||
| 168 | # | ||
| 169 | # clean_clean( ) - | ||
| 170 | # | ||
| 171 | sub clean_cache { | ||
| 172 | |||
| 173 | my $self = shift; | ||
| 174 | |||
| 175 | $self->{'_cache'}->maintain_cache($self->{'_cache'}->get_time()) | ||
| 176 | if($self->{'_cache'}); | ||
| 177 | } | ||
| 178 | |||
| 179 | |||
| 180 | # | ||
| 181 | # getResource( $lsid ) - This method resolves the specified LSID and invokes getAvailableServices | ||
| 182 | # to retreive the WSDL document containing the metadata and data service | ||
| 183 | # endpoints. An LS::Resource object is returned to the caller which is then | ||
| 184 | # used to make the subsequent getMetadata / getData requests. | ||
| 185 | # | ||
| 186 | # If an error occurs, check the LS::Client::errorString method for more detail. | ||
| 187 | # | ||
| 188 | sub getResource { | ||
| 189 | |||
| 190 | my ($self, $lsid) = @_; | ||
| 191 | |||
| 192 | $lsid = LS::ID->new($lsid) | ||
| 193 | unless(UNIVERSAL::isa($lsid, 'LS::ID')); | ||
| 194 | |||
| 195 | unless (UNIVERSAL::isa($lsid, 'LS::ID')) { | ||
| 196 | |||
| 197 | $self->recordError( 'Invalid LSID' ); | ||
| 198 | $self->addStackTrace(); | ||
| 199 | die($self->errorDetails()); | ||
| 200 | } | ||
| 201 | |||
| 202 | my $response = $self->getAvailableServices($lsid, @_); | ||
| 203 | |||
| 204 | return undef | ||
| 205 | unless($response); | ||
| 206 | |||
| 207 | local $/ = undef; | ||
| 208 | my $wsdl = $response->response(); | ||
| 209 | $wsdl = <$wsdl>; | ||
| 210 | |||
| 211 | # Moved here to make it load only if the user requests it | ||
| 212 | require LS::Resource; | ||
| 213 | |||
| 214 | return LS::Resource->new($lsid, $self, $wsdl); | ||
| 215 | } | ||
| 216 | |||
| 217 | |||
| 218 | # | ||
| 219 | # get_resource( $lsid ) - Synonym for getResource. | ||
| 220 | # | ||
| 221 | sub get_resource { | ||
| 222 | |||
| 223 | my $self = shift; | ||
| 224 | return $self->getResource(@_); | ||
| 225 | } | ||
| 226 | |||
| 227 | |||
| 228 | # | ||
| 229 | # _soap_call - An internal method usedt to make SOAP calls. | ||
| 230 | # | ||
| 231 | # Parameters are in the form of a hash: | ||
| 232 | # | ||
| 233 | # method - The method of the SOAP service to invoke. This | ||
| 234 | # is removed from the hash before passing the rest | ||
| 235 | # of it to the actual method of invocation. | ||
| 236 | # | ||
| 237 | # | ||
| 238 | # The rest of the option hash is passed to the SOAP method | ||
| 239 | # over the transport protocol. These are specified in the | ||
| 240 | # caller of _soap_call. | ||
| 241 | # | ||
| 242 | # If an error occurs, the internal class error variable will be | ||
| 243 | # set with the details. As always, it can be accessed via the | ||
| 244 | # LS::Client::errorString method | ||
| 245 | # | ||
| 246 | sub _soap_call { | ||
| 247 | |||
| 248 | my $self = shift; | ||
| 249 | my (%options) = @_; | ||
| 250 | |||
| 251 | my $method; | ||
| 252 | unless( ($method = $options{'method'}) ) { | ||
| 253 | |||
| 254 | $self->recordError( 'SOAP Method not specified' ); | ||
| 255 | $self->addStackTrace(); | ||
| 256 | die($self->errorDetails()); | ||
| 257 | } | ||
| 258 | |||
| 259 | # Remove method from the options hash | ||
| 260 | delete $options{'method'}; | ||
| 261 | |||
| 262 | my $host = $self->host(); | ||
| 263 | my $port = $self->port(); | ||
| 264 | my $path = $self->path(); | ||
| 265 | |||
| 266 | my $endpoint = $self->make_endpoint_url(); | ||
| 267 | |||
| 268 | # Get the SOAP interface or create it if we haven't already | ||
| 269 | my $SOAPclient = $self->{'_soap'}; | ||
| 270 | |||
| 271 | $SOAPclient = $self->{'_soap'} = LS::Client::SOAP->new(url=> "http://$host:$port$path") | ||
| 272 | unless($SOAPclient); | ||
| 273 | |||
| 274 | unless(UNIVERSAL::isa($SOAPclient, 'LS::Client::SOAP')) { | ||
| 275 | |||
| 276 | $self->recordError( 'Failed to create a LS::Client::SOAP' ); | ||
| 277 | $self->appendError( (LS::Client::SOAP->errorString() || 'No details available from SOAP client') ); | ||
| 278 | |||
| 279 | $self->addStackTrace( LS::Client::SOAP->getStackTrace() ); | ||
| 280 | |||
| 281 | die($self->errorDetails()); | ||
| 282 | } | ||
| 283 | |||
| 284 | $SOAPclient->credentials($self->{'_credentials'}) | ||
| 285 | if($self->{'_credentials'}); | ||
| 286 | |||
| 287 | # Invoke $method with %options as its parameters | ||
| 288 | my $response = $SOAPclient->$method(%options); | ||
| 289 | |||
| 290 | unless($response) { | ||
| 291 | |||
| 292 | $self->recordError( "LS::Client::SOAP::$method failed" ); | ||
| 293 | $self->appendError( ($SOAPclient->errorString() || ' No details available from SOAP client') ); | ||
| 294 | |||
| 295 | $self->addStackTrace( $SOAPclient->getStackTrace() ); | ||
| 296 | |||
| 297 | die($self->errorDetails()); | ||
| 298 | } | ||
| 299 | |||
| 300 | return $response; | ||
| 301 | } | ||
| 302 | |||
| 303 | |||
| 304 | # | ||
| 305 | # LSID Resolution Service method | ||
| 306 | # | ||
| 307 | |||
| 308 | # | ||
| 309 | # getAvailableServices - Queries the authority service for the available operations for the given LSID. | ||
| 310 | # The LSID may either be a string or an object of class LS::ID. The return value | ||
| 311 | # is a string, which is a WSDL document describing the operations, or undef | ||
| 312 | # if an error occurs. Error messages can be checked by calling the errorString | ||
| 313 | # method. | ||
| 314 | # | ||
| 315 | # Note that this method returns raw WSDL. You probably want to | ||
| 316 | # call getResource instead, unless you really intend to parse | ||
| 317 | # the WSDL yourself. | ||
| 318 | # | ||
| 319 | sub getAvailableServices { | ||
| 320 | |||
| 321 | my ($self, $lsid, %options) = @_; | ||
| 322 | |||
| 323 | $lsid = LS::ID->new($lsid) | ||
| 324 | unless(UNIVERSAL::isa($lsid, 'LS::ID')); | ||
| 325 | |||
| 326 | unless (UNIVERSAL::isa($lsid, 'LS::ID')) { | ||
| 327 | |||
| 328 | $self->recordError( 'Invalid LSID' ); | ||
| 329 | $self->addStackTrace(); | ||
| 330 | die($self->errorDetails()); | ||
| 331 | } | ||
| 332 | |||
| 333 | my $wsdl; | ||
| 334 | |||
| 335 | my $wsdl_resp = $self->{'_cache'}->lookupWSDL(lsid=> $lsid); | ||
| 336 | |||
| 337 | # Return the cached WSDL if found | ||
| 338 | return $wsdl_resp | ||
| 339 | if($wsdl_resp); | ||
| 340 | |||
| 341 | my $protocol = ${LS::Authority::WSDL::Constants::Protocols::HTTP}; | ||
| 342 | |||
| 343 | if(exists($options{'protocol'}) && defined($options{'protocol'})) { | ||
| 344 | |||
| 345 | $protocol = $options{'protocol'}; | ||
| 346 | |||
| 347 | unless($protocol eq ${LS::Authority::WSDL::Constants::Protocols::HTTP} || | ||
| 348 | $protocol eq ${LS::Authority::WSDL::Constants::Protocols::SOAP}) { | ||
| 349 | |||
| 350 | $self->recordError('Invalid protocol specified: ' . $options{'protocol'}); | ||
| 351 | $self->addStackTrace(); | ||
| 352 | die($self->errorDetails()); | ||
| 353 | } | ||
| 354 | } | ||
| 355 | |||
| 356 | $protocol = uc($protocol); | ||
| 357 | |||
| 358 | my $client_class = "LS::Client::$protocol"; | ||
| 359 | eval("use $client_class"); | ||
| 360 | |||
| 361 | die($@) | ||
| 362 | if($@); | ||
| 363 | |||
| 364 | my $url = $self->make_endpoint_url(); | ||
| 365 | |||
| 366 | my $client = $client_class->new(url=> $url); | ||
| 367 | |||
| 368 | # The WSDL is not cached so go get it | ||
| 369 | my $svc_rsp = $client->getAvailableServices(lsid=> $lsid, url=> $url); | ||
| 370 | |||
| 371 | return undef | ||
| 372 | unless(UNIVERSAL::isa($svc_rsp, 'LS::Service::Response')); | ||
| 373 | |||
| 374 | # This is important, the cache manager returns an LS::Service::Response | ||
| 375 | # with the LS::Service::Response::response set to an IO::File handle | ||
| 376 | # linked to a file from the cache | ||
| 377 | $svc_rsp = $self->{'_cache'}->cacheWSDL(lsid=> $lsid, | ||
| 378 | response=> $svc_rsp); | ||
| 379 | |||
| 380 | return $svc_rsp; | ||
| 381 | } | ||
| 382 | |||
| 383 | |||
| 384 | sub make_endpoint_url { | ||
| 385 | |||
| 386 | my $self = shift; | ||
| 387 | |||
| 388 | my $host = $self->host(); | ||
| 389 | my $port = $self->port(); | ||
| 390 | my $path = $self->path(); | ||
| 391 | |||
| 392 | my $endpoint; | ||
| 393 | |||
| 394 | # | ||
| 395 | # FIXME: This will probably go away | ||
| 396 | # | ||
| 397 | if($self->credentials()) { | ||
| 398 | |||
| 399 | my $username = $self->credentials()->username(); | ||
| 400 | my $password = $self->credentials()->password(); | ||
| 401 | |||
| 402 | # Setting username/password inside an http URI scheme is not standards | ||
| 403 | # compliant. | ||
| 404 | $endpoint = "http://$username:$password\@$host:$port$path"; | ||
| 405 | } | ||
| 406 | else { | ||
| 407 | |||
| 408 | $endpoint = "http://$host:$port$path"; | ||
| 409 | } | ||
| 410 | |||
| 411 | return $endpoint; | ||
| 412 | } | ||
| 413 | |||
| 414 | package LS::Authority::FAN; | ||
| 415 | |||
| 416 | use strict; | ||
| 417 | use warnings; | ||
| 418 | |||
| 419 | use base 'LS::Authority'; | ||
| 420 | |||
| 421 | # | ||
| 422 | # Foreign Authority Publication Service methods | ||
| 423 | # NOTE: This is subject to change | ||
| 424 | # | ||
| 425 | |||
| 426 | |||
| 427 | |||
| 428 | # | ||
| 429 | # notifyForeignAuthority( $lsid, $authorityName ) - | ||
| 430 | # | ||
| 431 | sub notifyForeignAuthority { | ||
| 432 | |||
| 433 | my ($self, $lsid, $authorityName) = @_; | ||
| 434 | |||
| 435 | $lsid = LS::ID->new($lsid) | ||
| 436 | unless(UNIVERSAL::isa($lsid, 'LS::ID')); | ||
| 437 | |||
| 438 | unless (UNIVERSAL::isa($lsid, 'LS::ID')) { | ||
| 439 | |||
| 440 | $self->recordError( 'Invalid LSID' ); | ||
| 441 | $self->addStackTrace(); | ||
| 442 | die($self->errorDetails()); | ||
| 443 | } | ||
| 444 | |||
| 445 | unless($authorityName) { | ||
| 446 | |||
| 447 | $self->recordError( 'Missing authority name' ); | ||
| 448 | $self->addStackTrace(); | ||
| 449 | die($self->errorDetails()); | ||
| 450 | } | ||
| 451 | |||
| 452 | my $svc_rsp = $self->_soap_call(method=> 'notifyForeignAuthority', | ||
| 453 | lsid=> $lsid, | ||
| 454 | authorityName=> $authorityName); | ||
| 455 | |||
| 456 | return $svc_rsp->response() | ||
| 457 | if(UNIVERSAL::isa($svc_rsp, 'LS::Service::Response')); | ||
| 458 | |||
| 459 | return undef; | ||
| 460 | } | ||
| 461 | |||
| 462 | |||
| 463 | # | ||
| 464 | # revokeNotificationForeignAuthority( $lsid, $authorityName ) - | ||
| 465 | # | ||
| 466 | sub revokeNotificationForeignAuthority { | ||
| 467 | |||
| 468 | my ($self, $lsid, $authorityName) = @_; | ||
| 469 | |||
| 470 | $lsid = LS::ID->new($lsid) | ||
| 471 | unless(UNIVERSAL::isa($lsid, 'LS::ID')); | ||
| 472 | |||
| 473 | unless (UNIVERSAL::isa($lsid, 'LS::ID')) { | ||
| 474 | |||
| 475 | $self->recordError( 'Invalid LSID' ); | ||
| 476 | $self->addStackTrace(); | ||
| 477 | die($self->errorDetails()); | ||
| 478 | } | ||
| 479 | |||
| 480 | unless($authorityName) { | ||
| 481 | |||
| 482 | $self->recordError( 'Missing authority name' ); | ||
| 483 | $self->addStackTrace(); | ||
| 484 | die($self->errorDetails()); | ||
| 485 | } | ||
| 486 | |||
| 487 | my $svc_rsp = $self->_soap_call(method=> 'revokeNotificationForeignAuthority', | ||
| 488 | lsid=> $lsid, | ||
| 489 | authorityName=> $authorityName); | ||
| 490 | |||
| 491 | return $svc_rsp->response() | ||
| 492 | if(UNIVERSAL::isa($svc_rsp, 'LS::Service::Response')); | ||
| 493 | |||
| 494 | return undef; | ||
| 495 | } | ||
| 496 | |||
| 497 | |||
| 498 | 1; | ||
| 499 | |||
| 500 | |||
| 501 | __END__ |