| 1 | package Bio::Phylo::PhyloWS; | ||
| 2 | use strict; | ||
| 3 | use warnings; | ||
| 4 | use base 'Bio::Phylo::NeXML::Writable'; | ||
| 5 | use Bio::Phylo::Util::CONSTANT 'looks_like_hash'; | ||
| 6 | use Bio::Phylo::Util::Exceptions 'throw'; | ||
| 7 | use Bio::Phylo::Util::Dependency 'URI::URL'; | ||
| 8 | use Bio::Phylo::Util::Logger; | ||
| 9 | |||
| 10 | our %MIMETYPE = ( | ||
| 11 | 'nexml' => 'application/xml;charset=UTF-8', | ||
| 12 | 'yaml' => 'application/x-yaml;charset=UTF-8', | ||
| 13 | 'rdf' => 'application/rdf+xml;charset=UTF-8', | ||
| 14 | 'rss1' => 'application/rdf+xml;charset=UTF-8', | ||
| 15 | 'phyloxml' => 'application/xml;charset=UTF-8', | ||
| 16 | 'nexus' => 'text/plain', | ||
| 17 | 'json' => 'text/javascript', | ||
| 18 | 'newick' => 'text/plain', | ||
| 19 | 'fasta' => 'text/plain', | ||
| 20 | ); | ||
| 21 | { | ||
| 22 | my @fields = \( my (%format, %section, %query, %authority) ); | ||
| 23 | my $logger = Bio::Phylo::Util::Logger->new; | ||
| 24 | |||
| 25 | =head1 NAME | ||
| 26 | |||
| 27 | Bio::Phylo::PhyloWS - Base class for phylogenetic web services | ||
| 28 | |||
| 29 | =head1 SYNOPSIS | ||
| 30 | |||
| 31 | # no direct usage, used by child classes | ||
| 32 | |||
| 33 | =head1 DESCRIPTION | ||
| 34 | |||
| 35 | This is the base class for clients and service that implement the PhyloWS | ||
| 36 | (L<http://evoinfo.nescent.org/PhyloWS>) recommendations. This base class | ||
| 37 | isn't used directly, it contains useful methods that are inherited by | ||
| 38 | its children. | ||
| 39 | |||
| 40 | =head1 METHODS | ||
| 41 | |||
| 42 | =head2 MUTATORS | ||
| 43 | |||
| 44 | =over | ||
| 45 | |||
| 46 | =item set_format() | ||
| 47 | |||
| 48 | Sets invocant's preferred serialization format. | ||
| 49 | |||
| 50 | Type : Mutator | ||
| 51 | Title : set_format | ||
| 52 | Usage : $obj->set_format($format); | ||
| 53 | Function: Assigns an object's serialization format. | ||
| 54 | Returns : Modified object. | ||
| 55 | Args : Argument must be a string. | ||
| 56 | |||
| 57 | =cut | ||
| 58 | |||
| 59 | sub set_format { | ||
| 60 | my ( $self, $base ) = @_; | ||
| 61 | $format{ $self->get_id } = $base; | ||
| 62 | return $self; | ||
| 63 | } | ||
| 64 | |||
| 65 | =item set_section() | ||
| 66 | |||
| 67 | Sets invocant's section ("table") to operate on, e.g. 'taxon', 'tree', etc. | ||
| 68 | |||
| 69 | Type : Mutator | ||
| 70 | Title : set_section | ||
| 71 | Usage : $obj->set_section($section); | ||
| 72 | Function: Sets section | ||
| 73 | Returns : Modified object. | ||
| 74 | Args : Argument must be a string. | ||
| 75 | |||
| 76 | =cut | ||
| 77 | |||
| 78 | sub set_section { | ||
| 79 | my ( $self, $section ) = @_; | ||
| 80 | $section{ $self->get_id } = $section; | ||
| 81 | return $self; | ||
| 82 | } | ||
| 83 | |||
| 84 | =item set_query() | ||
| 85 | |||
| 86 | Sets invocant's query parameter | ||
| 87 | |||
| 88 | Type : Mutator | ||
| 89 | Title : set_query | ||
| 90 | Usage : $obj->set_query($query); | ||
| 91 | Function: Assigns an object's query. | ||
| 92 | Returns : Modified object. | ||
| 93 | Args : Argument must be a string. | ||
| 94 | |||
| 95 | =cut | ||
| 96 | |||
| 97 | sub set_query { | ||
| 98 | my ( $self, $query ) = @_; | ||
| 99 | $query{ $self->get_id } = $query; | ||
| 100 | return $self; | ||
| 101 | } | ||
| 102 | |||
| 103 | =item set_authority() | ||
| 104 | |||
| 105 | Sets the authority prefix (e.g. TB2) for the implementing service | ||
| 106 | |||
| 107 | Type : Mutator | ||
| 108 | Title : set_authority | ||
| 109 | Usage : $obj->set_authority('TB2'); | ||
| 110 | Function: Sets authority prefix | ||
| 111 | Returns : $self | ||
| 112 | Args : String | ||
| 113 | Comments: | ||
| 114 | |||
| 115 | =cut | ||
| 116 | |||
| 117 | sub set_authority { | ||
| 118 | my ( $self, $auth ) = @_; | ||
| 119 | $authority{ $self->get_id } = $auth; | ||
| 120 | return $self; | ||
| 121 | } | ||
| 122 | |||
| 123 | =back | ||
| 124 | |||
| 125 | =head2 ACCESSORS | ||
| 126 | |||
| 127 | =over | ||
| 128 | |||
| 129 | =item get_url() | ||
| 130 | |||
| 131 | Gets invocant's url. This constructs the full url including section, authority | ||
| 132 | prefix, uid and query string. | ||
| 133 | |||
| 134 | Type : Accessor | ||
| 135 | Title : get_url | ||
| 136 | Usage : my $url = $obj->get_url; | ||
| 137 | Function: Returns the object's url. | ||
| 138 | Returns : A string | ||
| 139 | Args : | ||
| 140 | |||
| 141 | =cut | ||
| 142 | |||
| 143 | my $build_query_string = sub { | ||
| 144 | my ( $uri, %args ) = @_; | ||
| 145 | while ( my ( $key, $value ) = each %args ) { | ||
| 146 | if ( $key =~ m/^-/ ) { | ||
| 147 | $key =~ s/^-//; | ||
| 148 | if ( $uri =~ m/\?/ ) { | ||
| 149 | if ( $uri !~ m/[&\?]$/ ) { | ||
| 150 | $uri .= '&'; | ||
| 151 | } | ||
| 152 | $uri .= "${key}=${value}"; | ||
| 153 | } | ||
| 154 | else { | ||
| 155 | $uri .= '?' . "${key}=${value}"; | ||
| 156 | } | ||
| 157 | } | ||
| 158 | } | ||
| 159 | return $uri; | ||
| 160 | }; | ||
| 161 | |||
| 162 | sub get_url { | ||
| 163 | my $self = shift; | ||
| 164 | my $uri = $self->get_base_uri; | ||
| 165 | my %args; | ||
| 166 | |||
| 167 | # add format flag, if one is specified | ||
| 168 | if ( my $format = $self->get_format ) { | ||
| 169 | $args{'-format'} = $format; | ||
| 170 | } | ||
| 171 | |||
| 172 | # the section prefix, e.g. 'taxon' | ||
| 173 | $uri .= '/' if $uri !~ m|/$|; | ||
| 174 | $uri .= $self->get_section . '/'; | ||
| 175 | |||
| 176 | # the interaction is a query | ||
| 177 | if ( my $query = $self->get_query ) { | ||
| 178 | $logger->info("Constructing query URL"); | ||
| 179 | $uri .= $self->get_action; | ||
| 180 | my $kw = $self->get_query_keyword; | ||
| 181 | $args{'-'.$kw} = $query; | ||
| 182 | } | ||
| 183 | |||
| 184 | # the interaction is a record lookup | ||
| 185 | else { | ||
| 186 | $logger->info("Constructing lookup URL"); | ||
| 187 | $uri .= $self->get_authority . ':' . $self->get_guid; | ||
| 188 | } | ||
| 189 | |||
| 190 | return $build_query_string->($uri,%args,@_); | ||
| 191 | } | ||
| 192 | |||
| 193 | =item get_action() | ||
| 194 | |||
| 195 | Returns any appropriate action verb that needs to be composed into the URL. | ||
| 196 | By default this is C<find>, but child classes can override this to something | ||
| 197 | else (or nothing at all). | ||
| 198 | |||
| 199 | Type : Accessor | ||
| 200 | Title : get_action | ||
| 201 | Usage : my $action = $obj->get_action; | ||
| 202 | Function: Returns the object's url action. | ||
| 203 | Returns : A string | ||
| 204 | Args : | ||
| 205 | |||
| 206 | =cut | ||
| 207 | |||
| 208 | sub get_action { 'find' } | ||
| 209 | |||
| 210 | =item get_query_keyword() | ||
| 211 | |||
| 212 | Returns any appropriate action verb that needs to be composed into the query | ||
| 213 | string as the keyword to identify the search string. | ||
| 214 | By default this is C<query>, but child classes can override this to something | ||
| 215 | else (or nothing at all). | ||
| 216 | |||
| 217 | Type : Accessor | ||
| 218 | Title : get_query_keyword | ||
| 219 | Usage : my $keyword = $obj->get_query_keyword; | ||
| 220 | Function: Returns the object's query keyword | ||
| 221 | Returns : A string | ||
| 222 | Args : | ||
| 223 | |||
| 224 | =cut | ||
| 225 | |||
| 226 | sub get_query_keyword { 'query' } | ||
| 227 | |||
| 228 | =item get_url_prefix() | ||
| 229 | |||
| 230 | Constructs a url prefix to which an ID can be appended in order to resolve | ||
| 231 | to some resource. Combined with get_authority these form the moving parts | ||
| 232 | for how PhyloWS services could be plugged into the L<http://lsrn.org> | ||
| 233 | system. | ||
| 234 | |||
| 235 | Type : Accessor | ||
| 236 | Title : get_url_prefix | ||
| 237 | Usage : my $prefix = $obj->get_url_prefix; | ||
| 238 | Function: Returns the object's url prefix. | ||
| 239 | Returns : A string | ||
| 240 | Args : | ||
| 241 | |||
| 242 | =cut | ||
| 243 | |||
| 244 | sub get_url_prefix { | ||
| 245 | my $self = shift; | ||
| 246 | my $prefix = $self->get_base_uri; | ||
| 247 | $prefix .= '/' if $prefix !~ m|/$|; | ||
| 248 | $prefix .= $self->get_section . '/' . $self->get_authority . ':'; | ||
| 249 | return $prefix; | ||
| 250 | } | ||
| 251 | |||
| 252 | =item get_format() | ||
| 253 | |||
| 254 | Gets invocant's preferred serialization format | ||
| 255 | |||
| 256 | Type : Accessor | ||
| 257 | Title : get_format | ||
| 258 | Usage : my $format = $obj->get_format; | ||
| 259 | Function: Returns the object's preferred serialization format | ||
| 260 | Returns : A string | ||
| 261 | Args : None | ||
| 262 | |||
| 263 | =cut | ||
| 264 | |||
| 265 | sub get_format { | ||
| 266 | return $format{ shift->get_id }; | ||
| 267 | } | ||
| 268 | |||
| 269 | =item get_authority() | ||
| 270 | |||
| 271 | Gets the authority prefix (e.g. TB2) for the implementing service | ||
| 272 | |||
| 273 | Type : Accessor | ||
| 274 | Title : get_authority | ||
| 275 | Usage : my $auth = $obj->get_authority; | ||
| 276 | Function: Gets authority prefix | ||
| 277 | Returns : String | ||
| 278 | Args : None | ||
| 279 | Comments: | ||
| 280 | |||
| 281 | =cut | ||
| 282 | |||
| 283 | sub get_authority { | ||
| 284 | return $authority{ shift->get_id }; | ||
| 285 | } | ||
| 286 | |||
| 287 | =item get_section() | ||
| 288 | |||
| 289 | Gets invocant's section ("table") to operate on, e.g. 'taxon', 'tree', etc. | ||
| 290 | |||
| 291 | Type : Accessor | ||
| 292 | Title : get_section | ||
| 293 | Usage : my $section = $obj->get_section; | ||
| 294 | Function: Gets section | ||
| 295 | Returns : String | ||
| 296 | Args : None | ||
| 297 | |||
| 298 | =cut | ||
| 299 | |||
| 300 | sub get_section { | ||
| 301 | return $section{ shift->get_id }; | ||
| 302 | } | ||
| 303 | |||
| 304 | =item get_query() | ||
| 305 | |||
| 306 | Gets invocant's query parameter | ||
| 307 | |||
| 308 | Type : Accessor | ||
| 309 | Title : get_query | ||
| 310 | Usage : my $query = $obj->get_query; | ||
| 311 | Function: Retrieves an object's query. | ||
| 312 | Returns : Query | ||
| 313 | Args : None | ||
| 314 | |||
| 315 | =cut | ||
| 316 | |||
| 317 | sub get_query { | ||
| 318 | return $query{ shift->get_id }; | ||
| 319 | } | ||
| 320 | |||
| 321 | |||
| 322 | sub _cleanup { | ||
| 323 | my $self = shift; | ||
| 324 | my $id = $self->get_id; | ||
| 325 | for my $field (@fields) { | ||
| 326 | delete $field->{$id}; | ||
| 327 | } | ||
| 328 | } | ||
| 329 | |||
| 330 | =back | ||
| 331 | |||
| 332 | =cut | ||
| 333 | |||
| 334 | # podinherit_insert_token | ||
| 335 | |||
| 336 | =head1 SEE ALSO | ||
| 337 | |||
| 338 | There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo> | ||
| 339 | for any user or developer questions and discussions. | ||
| 340 | |||
| 341 | Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com> | ||
| 342 | |||
| 343 | =head1 CITATION | ||
| 344 | |||
| 345 | If you use Bio::Phylo in published research, please cite it: | ||
| 346 | |||
| 347 | B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen> | ||
| 348 | and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl. | ||
| 349 | I<BMC Bioinformatics> B<12>:63. | ||
| 350 | L<http://dx.doi.org/10.1186/1471-2105-12-63> | ||
| 351 | |||
| 352 | =cut | ||
| 353 | |||
| 354 | } | ||
| 355 | 1; |