Bio/AnalysisI.pm

   1 #
   2 # BioPerl module for Bio::AnalysisI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Martin Senger <martin.senger@gmail.com>
   7 # For copyright and disclaimer see below.
   8 #
   9
  10 # POD documentation - main docs before the code
  11
  12 =head1 NAME
  13
  14 Bio::AnalysisI - An interface to any (local or remote) analysis tool
  15
  16 =head1 SYNOPSIS
  17
  18 This is an interface module - you do not instantiate it.
  19 Use C<Bio::Tools::Run::Analysis> module:
  20
  21   use Bio::Tools::Run::Analysis;
  22   my $tool = Bio::Tools::Run::Analysis->new(@args);
  23
  24 =head1 DESCRIPTION
  25
  26 This interface contains all public methods for accessing and
  27 controlling local and remote analysis tools. It is meant to be used on
  28 the client side.
  29
  30 =head1 FEEDBACK
  31
  32 =head2 Mailing Lists
  33
  34 User feedback is an integral part of the evolution of this and other
  35 Bioperl modules. Send your comments and suggestions preferably to
  36 the Bioperl mailing list.  Your participation is much appreciated.
  37
  38   bioperl-l@bioperl.org                  - General discussion
  39   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  40
  41 =head2 Support
  42
  43 Please direct usage questions or support issues to the mailing list:
  44
  45 I<bioperl-l@bioperl.org>
  46
  47 rather than to the module maintainer directly. Many experienced and
  48 reponsive experts will be able look at the problem and quickly
  49 address it. Please include a thorough description of the problem
  50 with code and data examples if at all possible.
  51
  52 =head2 Reporting Bugs
  53
  54 Report bugs to the Bioperl bug tracking system to help us keep track
  55 of the bugs and their resolution. Bug reports can be submitted via the
  56 web:
  57
  58   https://redmine.open-bio.org/projects/bioperl/
  59
  60 =head1 AUTHOR
  61
  62 Martin Senger (martin.senger@gmail.com)
  63
  64 =head1 COPYRIGHT
  65
  66 Copyright (c) 2003, Martin Senger and EMBL-EBI.
  67 All Rights Reserved.
  68
  69 This module is free software; you can redistribute it and/or modify
  70 it under the same terms as Perl itself.
  71
  72 =head1 DISCLAIMER
  73
  74 This software is provided "as is" without warranty of any kind.
  75
  76 =head1 SEE ALSO
  77
  78 http://www.ebi.ac.uk/Tools/webservices/soaplab/guide
  79
  80 =head1 APPENDIX
  81
  82 This is actually the main documentation...
  83
  84 If you try to call any of these methods directly on this
  85 C<Bio::AnalysisI> object you will get a I<not implemented> error
  86 message. You need to call them on a C<Bio::Tools::Run::Analysis> object instead.
  87
  88 =cut
  89
  90
  91 # Let the code begin...
  92
  93 package Bio::AnalysisI;
  94 use strict;
  95
  96 use base qw(Bio::Root::RootI);
  97
  98 # -----------------------------------------------------------------------------
  99
 100 =head2 analysis_name
 101
 102  Usage   : $tool->analysis_name;
 103  Returns : a name of this analysis
 104  Args    : none
 105
 106 =cut
 107
 108 sub analysis_name { shift->throw_not_implemented(); }
 109
 110 # -----------------------------------------------------------------------------
 111
 112 =head2 analysis_spec
 113
 114  Usage   : $tool->analysis_spec;
 115  Returns : a hash reference describing this analysis
 116  Args    : none
 117
 118 The returned hash reference uses the following keys (not all of them always
 119 present, perhaps others present as well): C<name>, C<type>, C<version>,
 120 C<supplier>, C<installation>, C<description>.
 121
 122 Here is an example output:
 123
 124   Analysis 'edit.seqret':
 125         installation => EMBL-EBI
 126         description => Reads and writes (returns) sequences
 127         supplier => EMBOSS
 128         version => 2.6.0
 129         type => edit
 130         name => seqret
 131
 132 =cut
 133
 134 sub analysis_spec { shift->throw_not_implemented(); }
 135
 136 # -----------------------------------------------------------------------------
 137
 138 =head2 describe
 139
 140  Usage   : $tool->analysis_spec;
 141  Returns : an XML detailed description of this analysis
 142  Args    : none
 143
 144 The returned XML string contains metadata describing this analysis
 145 service. It includes also metadata returned (and easier used) by
 146 method C<analysis_spec>, C<input_spec> and C<result_spec>.
 147
 148 The DTD used for returned metadata is based on the adopted standard
 149 (BSA specification for analysis engine):
 150
 151   <!ELEMENT DsLSRAnalysis (analysis)+>
 152
 153   <!ELEMENT analysis (description?, input*, output*, extension?)>
 154
 155   <!ATTLIST analysis
 156       type          CDATA #REQUIRED
 157       name          CDATA #IMPLIED
 158       version       CDATA #IMPLIED
 159       supplier      CDATA #IMPLIED
 160       installation  CDATA #IMPLIED>
 161
 162   <!ELEMENT description ANY>
 163   <!ELEMENT extension ANY>
 164
 165   <!ELEMENT input (default?, allowed*, extension?)>
 166
 167   <!ATTLIST input
 168       type          CDATA #REQUIRED
 169       name          CDATA #REQUIRED
 170       mandatory     (true|false) "false">
 171
 172   <!ELEMENT default (#PCDATA)>
 173   <!ELEMENT allowed (#PCDATA)>
 174
 175   <!ELEMENT output (extension?)>
 176
 177   <!ATTLIST output
 178       type          CDATA #REQUIRED
 179       name          CDATA #REQUIRED>
 180
 181 But the DTD may be extended by provider-specific metadata. For
 182 example, the EBI experimental SOAP-based service on top of EMBOSS uses
 183 DTD explained at C<http://www.ebi.ac.uk/~senger/applab>.
 184
 185 =cut
 186
 187 sub describe { shift->throw_not_implemented(); }
 188
 189 # -----------------------------------------------------------------------------
 190
 191 =head2 input_spec
 192
 193  Usage   : $tool->input_spec;
 194  Returns : an array reference with hashes as elements
 195  Args    : none
 196
 197 The analysis input data are named, and can be also associated with a
 198 default value, with allowed values and with few other attributes. The
 199 names are important for feeding the service with the input data (the
 200 inputs are given to methods C<create_job>, C<Bio::AnalysisI|run>, and/or
 201 C<Bio::AnalysisI|wait_for> as name/value pairs).
 202
 203 Here is a (slightly shortened) example of an input specification:
 204
 205  $input_spec = [
 206           {
 207             'mandatory' => 'false',
 208             'type' => 'String',
 209             'name' => 'sequence_usa'
 210           },
 211           {
 212             'mandatory' => 'false',
 213             'type' => 'String',
 214             'name' => 'sequence_direct_data'
 215           },
 216           {
 217             'mandatory' => 'false',
 218             'allowed_values' => [
 219                                   'gcg',
 220                                   'gcg8',
 221                                   ...
 222                                   'raw'
 223                                 ],
 224             'type' => 'String',
 225             'name' => 'sformat'
 226           },
 227           {
 228             'mandatory' => 'false',
 229             'type' => 'String',
 230             'name' => 'sbegin'
 231           },
 232           {
 233             'mandatory' => 'false',
 234             'type' => 'String',
 235             'name' => 'send'
 236           },
 237           {
 238             'mandatory' => 'false',
 239             'type' => 'String',
 240             'name' => 'sprotein'
 241           },
 242           {
 243             'mandatory' => 'false',
 244             'type' => 'String',
 245             'name' => 'snucleotide'
 246           },
 247           {
 248             'mandatory' => 'false',
 249             'type' => 'String',
 250             'name' => 'sreverse'
 251           },
 252           {
 253             'mandatory' => 'false',
 254             'type' => 'String',
 255             'name' => 'slower'
 256           },
 257           {
 258             'mandatory' => 'false',
 259             'type' => 'String',
 260             'name' => 'supper'
 261           },
 262           {
 263             'mandatory' => 'false',
 264             'default' => 'false',
 265             'type' => 'String',
 266             'name' => 'firstonly'
 267           },
 268           {
 269             'mandatory' => 'false',
 270             'default' => 'fasta',
 271             'allowed_values' => [
 272                                   'gcg',
 273                                   'gcg8',
 274                                   'embl',
 275                                   ...
 276                                   'raw'
 277                                 ],
 278             'type' => 'String',
 279             'name' => 'osformat'
 280           }
 281         ];
 282
 283 =cut
 284
 285 sub input_spec { shift->throw_not_implemented(); }
 286
 287 # -----------------------------------------------------------------------------
 288
 289 =head2 result_spec
 290
 291  Usage   : $tool->result_spec;
 292  Returns : a hash reference with result names as keys
 293            and result types as values
 294  Args    : none
 295
 296 The analysis results are named and can be retrieved using their names
 297 by methods C<results> and C<result>.
 298
 299 Here is an example of the result specification (again for the service
 300 I<edit.seqret>):
 301
 302   $result_spec = {
 303           'outseq' => 'String',
 304           'report' => 'String',
 305           'detailed_status' => 'String'
 306         };
 307
 308 =cut
 309
 310 sub result_spec { shift->throw_not_implemented(); }
 311
 312 # -----------------------------------------------------------------------------
 313
 314 =head2 create_job
 315
 316  Usage   : $tool->create_job ( {'sequence'=>'tatat'} )
 317  Returns : Bio::Tools::Run::Analysis::Job
 318  Args    : data and parameters for this execution
 319            (in various formats)
 320
 321 Create an object representing a single execution of this analysis
 322 tool.
 323
 324 Call this method if you wish to "stage the scene" - to create a job
 325 with all input data but without actually running it. This method is
 326 called automatically from other methods (C<Bio::AnalysisI|run> and
 327 C<Bio::AnalysisI|wait_for>) so usually you do not need to call it directly.
 328
 329 The input data and prameters for this execution can be specified in
 330 various ways:
 331
 332 =over
 333
 334 =item array reference
 335
 336 The array has scalar elements of the form
 337
 338    name = [[@]value]
 339
 340 where C<name> is the name of an input data or input parameter (see
 341 method C<input_spec> for finding what names are recognized by this
 342 analysis) and C<value> is a value for this data/parameter. If C<value>
 343 is missing a 1 is assumed (which is convenient for the boolean
 344 options). If C<value> starts with C<@> it is treated as a local
 345 filename, and its contents is used as the data/parameter value.
 346
 347 =item hash reference
 348
 349 The same as with the array reference but now there is no need to use
 350 an equal sign. The hash keys are input names and hash values their
 351 data. The values can again start with a C<@> sign indicating a local
 352 filename.
 353
 354 =item scalar
 355
 356 In this case, the parameter represents a job ID obtained in some
 357 previous invocation - such job already exists on the server side, and
 358 we are just re-creating it here using the same job ID.
 359
 360 I<TBD: here we should allow the same by using a reference to the
 361 Bio::Tools::Run::Analysis::Job object.>
 362
 363 =item undef
 364
 365 Finally, if the parameter is undefined, ask server to create an empty
 366 job. The input data may be added later using C<set_data...>
 367 method(s) - see scripts/papplmaker.PLS for details.
 368
 369 =back
 370
 371 =cut
 372
 373 sub create_job { shift->throw_not_implemented(); }
 374
 375 # -----------------------------------------------------------------------------
 376
 377 =head2 run
 378
 379  Usage   : $tool->run ( ['sequence=@my.seq', 'osformat=embl'] )
 380  Returns : Bio::Tools::Run::Analysis::Job,
 381            representing started job (an execution)
 382  Args    : the same as for create_job
 383
 384 Create a job and start it, but do not wait for its completion.
 385
 386 =cut
 387
 388 sub run { shift->throw_not_implemented(); }
 389
 390 # -----------------------------------------------------------------------------
 391
 392 =head2 wait_for
 393
 394  Usage   : $tool->wait_for ( { 'sequence' => '@my,file' } )
 395  Returns : Bio::Tools::Run::Analysis::Job,
 396            representing finished job
 397  Args    : the same as for create_job
 398
 399 Create a job, start it and wait for its completion.
 400
 401 Note that this is a blocking method. It returns only after the
 402 executed job finishes, either normally or by an error.
 403
 404 Usually, after this call, you ask for results of the finished job:
 405
 406     $analysis->wait_for (...)->results;
 407
 408 =cut
 409
 410 sub wait_for { shift->throw_not_implemented(); }
 411
 412 # -----------------------------------------------------------------------------
 413 #
 414 #   Bio::AnalysisI::JobI
 415 #
 416 # -----------------------------------------------------------------------------
 417
 418 package Bio::AnalysisI::JobI;
 419
 420 =head1 Module Bio::AnalysisI::JobI
 421
 422 An interface to the public methods provided by C<Bio::Tools::Run::Analysis::Job>
 423 objects.
 424
 425 The C<Bio::Tools::Run::Analysis::Job> objects represent a created,
 426 running, or finished execution of an analysis tool.
 427
 428 The factory for these objects is module C<Bio::Tools::Run::Analysis>
 429 where the following methods return an
 430 C<Bio::Tools::Run::Analysis::Job> object:
 431
 432     create_job   (returning a prepared job)
 433     run          (returning a running job)
 434     wait_for     (returning a finished job)
 435
 436 =cut
 437
 438 use strict;
 439 use base qw(Bio::Root::RootI);
 440
 441 # -----------------------------------------------------------------------------
 442
 443 =head2 id
 444
 445  Usage   : $job->id;
 446  Returns : this job ID
 447  Args    : none
 448
 449 Each job (an execution) is identifiable by this unique ID which can be
 450 used later to re-create the same job (in other words: to re-connect to
 451 the same job). It is useful in cases when a job takes long time to
 452 finish and your client program does not want to wait for it within the
 453 same session.
 454
 455 =cut
 456
 457 sub id { shift->throw_not_implemented(); }
 458
 459 # -----------------------------------------------------------------------------
 460
 461 =head2 Bio::AnalysisI::JobI::run
 462
 463  Usage   : $job->run
 464  Returns : itself
 465  Args    : none
 466
 467 It starts previously created job.  The job already must have all input
 468 data filled-in. This differs from the method of the same name of the
 469 C<Bio::Tools::Run::Analysis> object where the C<Bio::AnalysisI::JobI::run> method
 470 creates also a new job allowing to set input data.
 471
 472 =cut
 473
 474 sub run { shift->throw_not_implemented(); }
 475
 476 # -----------------------------------------------------------------------------
 477
 478 =head2 Bio::AnalysisI::JobI::wait_for
 479
 480  Usage   : $job->wait_for
 481  Returns : itself
 482  Args    : none
 483
 484 It waits until a previously started execution of this job finishes.
 485
 486 =cut
 487
 488 sub wait_for { shift->throw_not_implemented(); }
 489
 490 # -----------------------------------------------------------------------------
 491
 492 =head2 terminate
 493
 494  Usage   : $job->terminate
 495  Returns : itself
 496  Args    : none
 497
 498 Stop the currently running job (represented by this object). This is a
 499 definitive stop, there is no way to resume it later.
 500
 501 =cut
 502
 503 sub terminate { shift->throw_not_implemented(); }
 504
 505 # -----------------------------------------------------------------------------
 506
 507 =head2 last_event
 508
 509  Usage   : $job->last_event
 510  Returns : an XML string
 511  Args    : none
 512
 513 It returns a short XML document showing what happened last with this
 514 job. This is the used DTD:
 515
 516    <!-- place for extensions -->
 517    <!ENTITY % event_body_template "(state_changed | heartbeat_progress | percent_progress | time_progress | step_progress)">
 518
 519    <!ELEMENT analysis_event (message?, (%event_body_template;)?)>
 520
 521    <!ATTLIST analysis_event
 522        timestamp  CDATA #IMPLIED>
 523
 524    <!ELEMENT message (#PCDATA)>
 525
 526    <!ELEMENT state_changed EMPTY>
 527    <!ENTITY % analysis_state "created | running | completed | terminated_by_request | terminated_by_error">
 528    <!ATTLIST state_changed
 529        previous_state  (%analysis_state;) "created"
 530        new_state       (%analysis_state;) "created">
 531
 532    <!ELEMENT heartbeat_progress EMPTY>
 533
 534    <!ELEMENT percent_progress EMPTY>
 535    <!ATTLIST percent_progress
 536        percentage CDATA #REQUIRED>
 537
 538    <!ELEMENT time_progress EMPTY>
 539    <!ATTLIST time_progress
 540        remaining CDATA #REQUIRED>
 541
 542    <!ELEMENT step_progress EMPTY>
 543    <!ATTLIST step_progress
 544        total_steps      CDATA #IMPLIED
 545        steps_completed CDATA #REQUIRED>
 546
 547 Here is an example what is returned after a job was created and
 548 started, but before it finishes (note that the example uses an
 549 analysis 'showdb' which does not need any input data):
 550
 551    use Bio::Tools::Run::Analysis;
 552    print new Bio::Tools::Run::Analysis (-name => 'display.showdb')
 553              ->run
 554              ->last_event;
 555
 556 It prints:
 557
 558    <?xml version = "1.0"?>
 559    <analysis_event>
 560      <message>Mar 3, 2003 5:14:46 PM (Europe/London)</message>
 561      <state_changed previous_state="created" new_state="running"/>
 562    </analysis_event>
 563
 564 The same example but now after it finishes:
 565
 566    use Bio::Tools::Run::Analysis;
 567    print new Bio::Tools::Run::Analysis (-name => 'display.showdb')
 568              ->wait_for
 569              ->last_event;
 570
 571    <?xml version = "1.0"?>
 572    <analysis_event>
 573      <message>Mar 3, 2003 5:17:14 PM (Europe/London)</message>
 574      <state_changed previous_state="running" new_state="completed"/>
 575    </analysis_event>
 576
 577 =cut
 578
 579 sub last_event { shift->throw_not_implemented(); }
 580
 581 # -----------------------------------------------------------------------------
 582
 583 =head2 status
 584
 585  Usage   : $job->status
 586  Returns : string describing the job status
 587  Args    : none
 588
 589 It returns one of the following strings (and perhaps more if a server
 590 implementation extended possible job states):
 591
 592    CREATED
 593    RUNNING
 594    COMPLETED
 595    TERMINATED_BY_REQUEST
 596    TERMINATED_BY_ERROR
 597
 598 =cut
 599
 600 sub status { shift->throw_not_implemented(); }
 601
 602 # -----------------------------------------------------------------------------
 603
 604 =head2 created
 605
 606  Usage   : $job->created (1)
 607  Returns : time when this job was created
 608  Args    : optional
 609
 610 Without any argument it returns a time of creation of this job in
 611 seconds, counting from the beginning of the UNIX epoch
 612 (1.1.1970). With a true argument it returns a formatted time, using
 613 rules described in C<Bio::Tools::Run::Analysis::Utils::format_time>.
 614
 615 =cut
 616
 617 sub created { shift->throw_not_implemented(); }
 618
 619 # -----------------------------------------------------------------------------
 620
 621 =head2 started
 622
 623  Usage   : $job->started (1)
 624  Returns : time when this job was started
 625  Args    : optional
 626
 627 See C<created>.
 628
 629 =cut
 630
 631 sub started { shift->throw_not_implemented(); }
 632
 633 # -----------------------------------------------------------------------------
 634
 635 =head2 ended
 636
 637  Usage   : $job->ended (1)
 638  Returns : time when this job was terminated
 639  Args    : optional
 640
 641 See C<created>.
 642
 643 =cut
 644
 645 sub ended { shift->throw_not_implemented(); }
 646
 647 # -----------------------------------------------------------------------------
 648
 649 =head2 elapsed
 650
 651  Usage   : $job->elapsed
 652  Returns : elapsed time of the execution of the given job
 653            (in milliseconds), or 0 of job was not yet started
 654  Args    : none
 655
 656 Note that some server implementations cannot count in millisecond - so
 657 the returned time may be rounded to seconds.
 658
 659 =cut
 660
 661 sub elapsed { shift->throw_not_implemented(); }
 662
 663 # -----------------------------------------------------------------------------
 664
 665 =head2 times
 666
 667  Usage   : $job->times ('formatted')
 668  Returns : a hash refrence with all time characteristics
 669  Args    : optional
 670
 671 It is a convenient method returning a hash reference with the folowing
 672 keys:
 673
 674    created
 675    started
 676    ended
 677    elapsed
 678
 679 See C<create> for remarks on time formating.
 680
 681 An example - both for unformatted and formatted times:
 682
 683    use Data::Dumper;
 684    use Bio::Tools::Run::Analysis;
 685    my $rh = Bio::Tools::Run::Analysis->new(-name => 'nucleic_cpg_islands.cpgplot')
 686              ->wait_for ( { 'sequence_usa' => 'embl:hsu52852' } )
 687              ->times (1);
 688    print Data::Dumper->Dump ( [$rh], ['Times']);
 689    $rh = Bio::Tools::Run::Analysis->new(-name => 'nucleic_cpg_islands.cpgplot')
 690              ->wait_for ( { 'sequence_usa' => 'embl:AL499624' } )
 691              ->times;
 692    print Data::Dumper->Dump ( [$rh], ['Times']);
 693
 694    $Times = {
 695            'ended'   => 'Mon Mar  3 17:52:06 2003',
 696            'started' => 'Mon Mar  3 17:52:05 2003',
 697            'elapsed' => '1000',
 698            'created' => 'Mon Mar  3 17:52:05 2003'
 699          };
 700    $Times = {
 701            'ended'   => '1046713961',
 702            'started' => '1046713926',
 703            'elapsed' => '35000',
 704            'created' => '1046713926'
 705          };
 706
 707 =cut
 708
 709 sub times { shift->throw_not_implemented(); }
 710
 711 # -----------------------------------------------------------------------------
 712
 713 =head2 results
 714
 715  Usage   : $job->results (...)
 716  Returns : one or more results created by this job
 717  Args    : various, see belou
 718
 719 This is a complex method trying to make sense for all kinds of
 720 results. Especially it tries to help to put binary results (such as
 721 images) into local files. Generally it deals with fhe following facts:
 722
 723 =over
 724
 725 =item *
 726
 727 Each analysis tool may produce more results.
 728
 729 =item *
 730
 731 Some results may contain binary data not suitable for printing into a
 732 terminal window.
 733
 734 =item *
 735
 736 Some results may be split into variable number of parts (this is
 737 mainly true for the image results that can consist of more *.png
 738 files).
 739
 740 =back
 741
 742 Note also that results have names to distinguish if there are more of
 743 them. The names can be obtained by method C<result_spec>.
 744
 745 Here are the rules how the method works:
 746
 747     Retrieving NAMED results:
 748     -------------------------
 749      results ('name1', ...)   => return results as they are, no storing into files
 750
 751      results ( { 'name1' => 'filename', ... } )  => store into 'filename', return 'filename'
 752      results ( 'name1=filename', ...)            => ditto
 753
 754      results ( { 'name1' => '-', ... } )         => send result to the STDOUT, do not return anything
 755      results ( 'name1=-', ...)                   => ditto
 756
 757      results ( { 'name1' => '@', ... } )  => store into file whose name is invented by
 758                                              this method, perhaps using RESULT_NAME_TEMPLATE env
 759      results ( 'name1=@', ...)            => ditto
 760
 761      results ( { 'name1' => '?', ... } )  => find of what type is this result and then use
 762                                              {'name1'=>'@' for binary files, and a regular
 763                                              return for non-binary files
 764      results ( 'name=?', ...)             => ditto
 765
 766     Retrieving ALL results:
 767     -----------------------
 768      results()     => return all results as they are, no storing into files
 769
 770      results ('@') => return all results, as if each of them given
 771                       as {'name' => '@'} (see above)
 772
 773      results ('?') => return all results, as if each of them given
 774                       as {'name' => '?'} (see above)
 775
 776     Misc:
 777     -----
 778      * any result can be returned as a scalar value, or as an array reference
 779        (the latter is used for results consisting of more parts, such images);
 780        this applies regardless whether the returned result is the result itself
 781        or a filename created for the result
 782
 783      * look in the documentation of the C<panalysis[.PLS]> script for examples
 784        (especially how to use various templates for inventing file names)
 785
 786 =cut
 787
 788 sub results { shift->throw_not_implemented(); }
 789
 790 # -----------------------------------------------------------------------------
 791
 792 =head2 result
 793
 794  Usage   : $job->result (...)
 795  Returns : the first result
 796  Args    : see 'results'
 797
 798 =cut
 799
 800 sub result { shift->throw_not_implemented(); }
 801
 802 # -----------------------------------------------------------------------------
 803
 804 =head2 remove
 805
 806  Usage   : $job->remove
 807  Returns : 1
 808  Args    : none
 809
 810 The job object is not actually removed in this time but it is marked
 811 (setting 1 to C<_destroy_on_exit> attribute) as ready for deletion when
 812 the client program ends (including a request to server to forget the job
 813 mirror object on the server side).
 814
 815 =cut
 816
 817 sub remove { shift->throw_not_implemented(); }
 818
 819 # -----------------------------------------------------------------------------
 820
 821 1;
 822 __END__
 823