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