Bio/Factory/ObjectBuilderI.pm

   1 #
   2 # BioPerl module for Bio::Factory::ObjectBuilderI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
   7 #
   8 # Copyright Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 #
  13 # (c) Hilmar Lapp, hlapp at gmx.net, 2002.
  14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  15 #
  16 # You may distribute this module under the same terms as perl itself.
  17 # Refer to the Perl Artistic License (see the license accompanying this
  18 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  19 # for the terms under which you may use, modify, and redistribute this module.
  20 #
  21 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  22 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  23 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  24 #
  25
  26 # POD documentation - main docs before the code
  27
  28 =head1 NAME
  29
  30 Bio::Factory::ObjectBuilderI - Interface for an object builder
  31
  32 =head1 SYNOPSIS
  33
  34 Give standard usage here
  35
  36 =head1 DESCRIPTION
  37
  38 An object builder is different from an object factory in that it
  39 accumulates information for the object and finally, or constantly,
  40 depending on the implementation, builds the object. It also allows for
  41 implementations that can tell the information feed in which kind of
  42 information the builder is interested in which not. In addition, the
  43 implementation may choose to filter, transform, or completely ignore
  44 certain content it is fed for certain slots.
  45
  46 Implementations will hence be mostly used by stream-based parsers to
  47 parse only desired content, and/or skip over undesired entries.
  48
  49 =head1 FEEDBACK
  50
  51 =head2 Mailing Lists
  52
  53 User feedback is an integral part of the evolution of this and other
  54 Bioperl modules. Send your comments and suggestions preferably to
  55 the Bioperl mailing list.  Your participation is much appreciated.
  56
  57   bioperl-l@bioperl.org                  - General discussion
  58   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  59
  60 =head2 Support
  61
  62 Please direct usage questions or support issues to the mailing list:
  63
  64 I<bioperl-l@bioperl.org>
  65
  66 rather than to the module maintainer directly. Many experienced and
  67 reponsive experts will be able look at the problem and quickly
  68 address it. Please include a thorough description of the problem
  69 with code and data examples if at all possible.
  70
  71 =head2 Reporting Bugs
  72
  73 Report bugs to the Bioperl bug tracking system to help us keep track
  74 of the bugs and their resolution. Bug reports can be submitted via the
  75 web:
  76
  77   https://github.com/bioperl/bioperl-live/issues
  78
  79 =head1 AUTHOR - Hilmar Lapp
  80
  81 Email hlapp at gmx.net
  82
  83 =head1 APPENDIX
  84
  85 The rest of the documentation details each of the object methods.
  86 Internal methods are usually preceded with a _
  87
  88 =cut
  89
  90
  91 # Let the code begin...
  92
  93
  94 package Bio::Factory::ObjectBuilderI;
  95 use strict;
  96 use Carp;
  97
  98 use base qw(Bio::Root::RootI);
  99
 100 =head2 want_slot
 101
 102  Title   : want_slot
 103  Usage   :
 104  Function: Whether or not the object builder wants to populate the
 105            specified slot of the object to be built.
 106
 107            The slot can be specified either as the name of the
 108            respective method, or the initialization parameter that
 109            would be otherwise passed to new() of the object to be
 110            built.
 111
 112  Example :
 113  Returns : TRUE if the object builder wants to populate the slot, and
 114            FALSE otherwise.
 115  Args    : the name of the slot (a string)
 116
 117
 118 =cut
 119
 120 sub want_slot{
 121     shift->throw_not_implemented();
 122 }
 123
 124 =head2 add_slot_value
 125
 126  Title   : add_slot_value
 127  Usage   :
 128  Function: Adds one or more values to the specified slot of the object
 129            to be built.
 130
 131            Naming the slot is the same as for want_slot().
 132
 133            The object builder may further filter the content to be
 134            set, or even completely ignore the request.
 135
 136            If this method reports failure, the caller should not add
 137            more values to the same slot. In addition, the caller may
 138            find it appropriate to abandon the object being built
 139            altogether.
 140
 141  Example :
 142  Returns : TRUE on success, and FALSE otherwise
 143  Args    : the name of the slot (a string)
 144            parameters determining the value to be set
 145
 146
 147 =cut
 148
 149 sub add_slot_value{
 150     shift->throw_not_implemented();
 151 }
 152
 153 =head2 want_object
 154
 155  Title   : want_object
 156  Usage   :
 157  Function: Whether or not the object builder is still interested in
 158            continuing with the object being built.
 159
 160            If this method returns FALSE, the caller should not add any
 161            more values to slots, or otherwise risks that the builder
 162            throws an exception. In addition, make_object() is likely
 163            to return undef after this method returned FALSE.
 164
 165  Example :
 166  Returns : TRUE if the object builder wants to continue building
 167            the present object, and FALSE otherwise.
 168  Args    : none
 169
 170
 171 =cut
 172
 173 sub want_object{
 174     shift->throw_not_implemented();
 175 }
 176
 177 =head2 make_object
 178
 179  Title   : make_object
 180  Usage   :
 181  Function: Get the built object.
 182
 183            This method is allowed to return undef if no value has ever
 184            been added since the last call to make_object(), or if
 185            want_object() returned FALSE (or would have returned FALSE)
 186            before calling this method.
 187
 188            For an implementation that allows consecutive building of
 189            objects, a caller must call this method once, and only
 190            once, between subsequent objects to be built. I.e., a call
 191            to make_object implies 'end_object.'
 192
 193  Example :
 194  Returns : the object that was built
 195  Args    : none
 196
 197
 198 =cut
 199
 200 sub make_object{
 201     shift->throw_not_implemented();
 202 }
 203
 204 1;