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