maint: remove Travis stuff which has been replaced with Github actions (#325)
[bioperl-live.git] / lib / Bio / Factory / ObjectFactory.pm
bloba496dfd8186093e8dc285ccf74cf305762048c39
2 # BioPerl module for Bio::Factory::ObjectFactory
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
8 # Copyright Hilmar Lapp
10 # You may distribute this module under the same terms as perl itself
13 # (c) Hilmar Lapp, hlapp at gmx.net, 2003.
14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2003.
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.
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.
26 # POD documentation - main docs before the code
28 =head1 NAME
30 Bio::Factory::ObjectFactory - Instantiates a new Bio::Root::RootI (or derived class) through a factory
32 =head1 SYNOPSIS
34 use Bio::Factory::ObjectFactory;
36 my $factory = Bio::Factory::ObjectFactory->new(-type => 'Bio::Ontology::GOterm');
37 my $term = $factory->create_object(-name => 'peroxisome',
38 -ontology => 'Gene Factory',
39 -identifier => 'GO:0005777');
42 =head1 DESCRIPTION
44 This object will build L<Bio::Root::RootI> objects generically.
46 =head1 FEEDBACK
48 =head2 Mailing Lists
50 User feedback is an integral part of the evolution of this and other
51 Bioperl modules. Send your comments and suggestions preferably to
52 the Bioperl mailing list. Your participation is much appreciated.
54 bioperl-l@bioperl.org - General discussion
55 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
57 =head2 Support
59 Please direct usage questions or support issues to the mailing list:
61 I<bioperl-l@bioperl.org>
63 rather than to the module maintainer directly. Many experienced and
64 reponsive experts will be able look at the problem and quickly
65 address it. Please include a thorough description of the problem
66 with code and data examples if at all possible.
68 =head2 Reporting Bugs
70 Report bugs to the Bioperl bug tracking system to help us keep track
71 of the bugs and their resolution. Bug reports can be submitted via the
72 web:
74 https://github.com/bioperl/bioperl-live/issues
76 =head1 AUTHOR - Hilmar Lapp
78 Email hlapp at gmx.net
81 =head1 CONTRIBUTORS
83 This is mostly copy-and-paste with subsequent adaptation from
84 Bio::Seq::SeqFactory by Jason Stajich. Most credits should in fact go
85 to him.
87 =head1 APPENDIX
89 The rest of the documentation details each of the object methods.
90 Internal methods are usually preceded with a _
92 =cut
95 # Let the code begin...
98 package Bio::Factory::ObjectFactory;
100 use strict;
103 use base qw(Bio::Root::Root Bio::Factory::ObjectFactoryI);
105 =head2 new
107 Title : new
108 Usage : my $obj = Bio::Factory::ObjectFactory->new();
109 Function: Builds a new Bio::Factory::ObjectFactory object
110 Returns : Bio::Factory::ObjectFactory
111 Args : -type => string, name of a L<Bio::Root::RootI> derived class.
112 There is no default.
113 -interface => string, name of the interface or class any type
114 specified needs to at least implement.
115 The default is Bio::Root::RootI.
117 =cut
119 sub new {
120 my($class,@args) = @_;
122 my $self = $class->SUPER::new(@args);
124 my ($type,$interface) = $self->_rearrange([qw(TYPE INTERFACE)], @args);
126 $self->{'_loaded_types'} = {};
127 $self->interface($interface || "Bio::Root::RootI");
128 $self->type($type) if $type;
130 return $self;
134 =head2 create_object
136 Title : create_object
137 Usage : my $seq = $factory->create_object(<named parameters>);
138 Function: Instantiates a new object of the previously set type.
140 This object allows us to genericize the instantiation of
141 objects.
143 You must have provided -type at instantiation, or have
144 called type($mytype) before you can call this method.
146 Returns : an object of the type returned by type()
148 The return type is configurable using new(-type =>"..."),
149 or by calling $self->type("My::Fancy::Class").
150 Args : Initialization parameters specific to the type of
151 object we want. Check the POD of the class you set as type.
153 =cut
155 sub create_object {
156 my ($self,@args) = @_;
158 my $type = $self->type(); # type has already been loaded upon set
159 return $type->new(-verbose => $self->verbose, @args);
162 =head2 type
164 Title : type
165 Usage : $obj->type($newval)
166 Function: Get/set the type of object to be created.
168 This may be changed at any time during the lifetime of this
169 factory.
171 Returns : value of type (a string)
172 Args : newvalue (optional, a string)
175 =cut
177 sub type{
178 my $self = shift;
180 if(@_) {
181 my $type = shift;
182 if($type && (! $self->{'_loaded_types'}->{$type})) {
183 eval {
184 $self->_load_module($type);
186 if( $@ ) {
187 $self->throw("module for '$type' failed to load: ".
188 $@);
190 my $o = bless {},$type;
191 if(!$self->_validate_type($o)) { # this may throw an exception
192 $self->throw("'$type' is not valid for factory ".ref($self));
194 $self->{'_loaded_types'}->{$type} = 1;
196 return $self->{'type'} = $type;
198 return $self->{'type'};
201 =head2 interface
203 Title : interface
204 Usage : $obj->interface($newval)
205 Function: Get/set the interface or base class that supplied types
206 must at least implement (inherit from).
207 Example :
208 Returns : value of interface (a scalar)
209 Args : on set, new value (a scalar or undef, optional)
212 =cut
214 sub interface{
215 my $self = shift;
216 my $interface = shift;
218 if($interface) {
219 return $self->{'interface'} = $interface;
221 return $self->{'interface'};
224 =head2 _validate_type
226 Title : _validate_type
227 Usage : $factory->_validate_type($object)
228 Function: Called to let derived factories validate the type set
229 via type().
231 The default implementation here checks whether the supplied
232 object skeleton implements the interface set via -interface
233 upon factory instantiation.
235 Example :
236 Returns : TRUE if the type is to be considered valid, and FALSE otherwise.
237 Instead of returning FALSE this method may also just throw
238 an informative exception.
240 The default implementation here will throw an exception
241 if the supplied object does not inherit from the interface
242 provided by the interface() method.
244 Args : A hash reference blessed into the specified type, allowing
245 queries like isa().
248 =cut
250 sub _validate_type{
251 my ($self,$obj) = @_;
253 if(! $obj->isa($self->interface())) {
254 $self->throw("invalid type: '".ref($obj).
255 "' does not implement '".$self->interface()."'");
257 return 1;
260 #####################################################################
261 # aliases for naming consistency or other reasons #
262 #####################################################################
264 *create = \&create_object;