| 1 | package Bio::Phylo::PhyloWS::Client; | ||
| 2 | use strict; | ||
| 3 | use warnings; | ||
| 4 | use base 'Bio::Phylo::PhyloWS'; | ||
| 5 | use Bio::Phylo::IO 'parse'; | ||
| 6 | use Bio::Phylo::Factory; | ||
| 7 | use Bio::Phylo::Util::Logger; | ||
| 8 | use Bio::Phylo::Util::Exceptions 'throw'; | ||
| 9 | use Bio::Phylo::Util::CONSTANT 'looks_like_hash'; | ||
| 10 | use Bio::Phylo::Util::Dependency qw'LWP::UserAgent XML::Twig'; | ||
| 11 | { | ||
| 12 | my @fields = \( my (%ua) ); | ||
| 13 | my $logger = Bio::Phylo::Util::Logger->new; | ||
| 14 | my $fac = Bio::Phylo::Factory->new; | ||
| 15 | |||
| 16 | =head1 NAME | ||
| 17 | |||
| 18 | Bio::Phylo::PhyloWS::Client - Base class for phylogenetic web service clients | ||
| 19 | |||
| 20 | =head1 SYNOPSIS | ||
| 21 | |||
| 22 | #!/usr/bin/perl | ||
| 23 | use strict; | ||
| 24 | use warnings; | ||
| 25 | use Bio::Phylo::Factory; | ||
| 26 | |||
| 27 | my $fac = Bio::Phylo::Factory->new; | ||
| 28 | my $client = $fac->create_client( | ||
| 29 | '-base_uri' => 'http://nexml-dev.nescent.org/nexml/phylows/tolweb/phylows/', | ||
| 30 | '-authority' => 'uBioNB', | ||
| 31 | ); | ||
| 32 | my $desc = $client->get_query_result( | ||
| 33 | '-query' => 'Homo sapiens', | ||
| 34 | '-section' => 'taxon', | ||
| 35 | ); | ||
| 36 | for my $res ( @{ $desc->get_entities } ) { | ||
| 37 | my $proj = $client->get_record( '-guid' => $res->get_guid ); | ||
| 38 | print $proj->to_nexus, "\n"; | ||
| 39 | } | ||
| 40 | |||
| 41 | =head1 DESCRIPTION | ||
| 42 | |||
| 43 | This is the base class for clients connecting to services that implement | ||
| 44 | the PhyloWS (L<http://evoinfo.nescent.org/PhyloWS>) recommendations. | ||
| 45 | |||
| 46 | =head1 METHODS | ||
| 47 | |||
| 48 | =head2 CONSTRUCTOR | ||
| 49 | |||
| 50 | =over | ||
| 51 | |||
| 52 | =item new() | ||
| 53 | |||
| 54 | Type : Constructor | ||
| 55 | Title : new | ||
| 56 | Usage : my $phylows = Bio::Phylo::PhyloWS::Client->new( -url => $url ); | ||
| 57 | Function: Instantiates Bio::Phylo::PhyloWS::Client object | ||
| 58 | Returns : a Bio::Phylo::PhyloWS::Client object | ||
| 59 | Args : Required: -url => $url | ||
| 60 | Optional: any number of setters. For example, | ||
| 61 | Bio::Phylo::PhyloWS->new( -name => $name ) | ||
| 62 | will call set_name( $name ) internally | ||
| 63 | |||
| 64 | =cut | ||
| 65 | |||
| 66 | sub new { | ||
| 67 | |||
| 68 | # could be child class | ||
| 69 | my $class = shift; | ||
| 70 | |||
| 71 | # go up inheritance tree, eventually get an ID | ||
| 72 | my $self = $class->SUPER::new(@_); | ||
| 73 | |||
| 74 | # store a user agent object to delegate http stuff to | ||
| 75 | if ( not $self->get_ua ) { | ||
| 76 | my $ua = LWP::UserAgent->new; | ||
| 77 | $ua->timeout(300); | ||
| 78 | $ua->env_proxy; | ||
| 79 | $self->set_ua($ua); | ||
| 80 | } | ||
| 81 | return $self; | ||
| 82 | } | ||
| 83 | my $ua = sub { | ||
| 84 | return $ua{ shift->get_id }; | ||
| 85 | }; | ||
| 86 | |||
| 87 | =back | ||
| 88 | |||
| 89 | =head2 MUTATORS | ||
| 90 | |||
| 91 | =over | ||
| 92 | |||
| 93 | =item set_ua() | ||
| 94 | |||
| 95 | Assigns a new L<LWP::UserAgent> object that the client uses to communicate | ||
| 96 | with the service. Typically you don't have to use this unless you have to | ||
| 97 | configure a user agent for things such as proxies. Normally a default user | ||
| 98 | agent is instantiated when the client constructor is called. | ||
| 99 | |||
| 100 | Type : Mutator | ||
| 101 | Title : set_ua | ||
| 102 | Usage : $obj->set_ua( LWP::UserAgent->new ); | ||
| 103 | Function: Assigns another (non-default) user agent | ||
| 104 | Returns : $self | ||
| 105 | Args : An LWP::UserAgent object (or child class) | ||
| 106 | |||
| 107 | =cut | ||
| 108 | |||
| 109 | sub set_ua { | ||
| 110 | my $self = shift; | ||
| 111 | my $arg = shift; | ||
| 112 | if ( UNIVERSAL::isa( $arg, 'LWP::UserAgent' ) ) { | ||
| 113 | $ua{ $self->get_id } = $arg; | ||
| 114 | } | ||
| 115 | else { | ||
| 116 | throw 'BadArgs' => "'$arg' is not an LWP::UserAgent"; | ||
| 117 | } | ||
| 118 | return $self; | ||
| 119 | } | ||
| 120 | |||
| 121 | =back | ||
| 122 | |||
| 123 | =head2 ACCESSORS | ||
| 124 | |||
| 125 | =over | ||
| 126 | |||
| 127 | =item get_query_result() | ||
| 128 | |||
| 129 | Gets search query result | ||
| 130 | |||
| 131 | Type : Accessor | ||
| 132 | Title : get_query_result | ||
| 133 | Usage : my $res = $obj->get_query_result( -query => $query ); | ||
| 134 | Function: Returns Bio::Phylo::PhyloWS::Description object | ||
| 135 | Returns : A string | ||
| 136 | Args : Required: -query => $cql_query | ||
| 137 | Optional: -section, -recordSchema | ||
| 138 | |||
| 139 | =cut | ||
| 140 | |||
| 141 | my $rss_handler = sub { | ||
| 142 | my ($create_method,$self,$twig,$elt) = @_; | ||
| 143 | my %known = ( | ||
| 144 | 'title' => '-name', | ||
| 145 | 'description' => '-desc', | ||
| 146 | 'link' => '-link', | ||
| 147 | ); | ||
| 148 | my ( %args, @meta ); | ||
| 149 | for my $child ( $elt->children ) { | ||
| 150 | my $tag = $child->tag; | ||
| 151 | if ( my $key = $known{$tag} ) { | ||
| 152 | $args{$key} = $child->text; | ||
| 153 | } | ||
| 154 | elsif ( $tag ne 'items' ) { | ||
| 155 | my $predicate = $tag; | ||
| 156 | my ( $prefix, $namespace, $object ); | ||
| 157 | if ( $tag =~ /(.+?):/ ) { | ||
| 158 | $prefix = $1; | ||
| 159 | $namespace = $child->namespace; | ||
| 160 | } | ||
| 161 | if ( ! ( $object = $child->att('rdf:about') ) ) { | ||
| 162 | $object = $child->text; | ||
| 163 | } | ||
| 164 | push @meta, $fac->create_meta( | ||
| 165 | '-namespaces' => { $prefix => $namespace }, | ||
| 166 | '-triple' => { $predicate => $object }, | ||
| 167 | ); | ||
| 168 | } | ||
| 169 | } | ||
| 170 | my $obj = $fac->$create_method(%args); | ||
| 171 | $obj->add_meta($_) for @meta; | ||
| 172 | my $pre = $self->get_url_prefix; | ||
| 173 | my $link = $obj->get_link; | ||
| 174 | $link =~ s/^\Q$pre\E(.+?)?/$1/i; | ||
| 175 | $obj->set_guid($link); | ||
| 176 | return $obj; | ||
| 177 | }; | ||
| 178 | |||
| 179 | sub get_query_result { | ||
| 180 | my $self = shift; | ||
| 181 | $logger->debug("going to get query result"); | ||
| 182 | if ( my %args = looks_like_hash @_ ) { | ||
| 183 | |||
| 184 | # these fields need to be set first before get_url returns | ||
| 185 | # a sane response | ||
| 186 | $self->set_query( $args{'-query'} || throw 'BadArgs' => "Need query argument" ); | ||
| 187 | $logger->debug("set query ".$args{'-query'}); | ||
| 188 | |||
| 189 | $self->set_section( $args{'-section'} || 'taxon' ); | ||
| 190 | $self->set_format( 'rss1' ); | ||
| 191 | my $rs = $args{'-recordSchema'} || $args{'-section'} || 'taxon'; | ||
| 192 | my $url = $self->get_url( '-recordSchema' => $rs ); | ||
| 193 | $url =~ s/&/&/g; | ||
| 194 | $logger->debug("URL: $url"); | ||
| 195 | |||
| 196 | # do the request | ||
| 197 | my $response = $ua->($self)->get($url); | ||
| 198 | if ( $response->is_success ) { | ||
| 199 | $logger->debug("request succeeded"); | ||
| 200 | my $content = $response->content; | ||
| 201 | use Data::Dumper; | ||
| 202 | print Dumper($response); | ||
| 203 | |||
| 204 | $self->set_section($rs); | ||
| 205 | my $desc = $self->parse_query_result($content); | ||
| 206 | if ( $@ ) { | ||
| 207 | $logger->fatal("Error fetching from $url"); | ||
| 208 | $logger->fatal($content); | ||
| 209 | throw 'NetworkError' => $@; | ||
| 210 | } | ||
| 211 | else { | ||
| 212 | $self->set_section( $args{'-section'} || 'taxon' ); | ||
| 213 | return $desc; | ||
| 214 | } | ||
| 215 | } | ||
| 216 | else { | ||
| 217 | throw 'NetworkError' => "Error fetching from $url: " | ||
| 218 | . $response->status_line; | ||
| 219 | } | ||
| 220 | } | ||
| 221 | } | ||
| 222 | |||
| 223 | =item parse_query_result() | ||
| 224 | |||
| 225 | Parses a raw query result | ||
| 226 | |||
| 227 | Type : Accessor | ||
| 228 | Title : parse_query_result | ||
| 229 | Usage : my $desc = $obj->parse_query_result($content); | ||
| 230 | Function: Parses a raw query result | ||
| 231 | Returns : Bio::Phylo::PhyloWS::Resource::Description object | ||
| 232 | Args : Raw result content | ||
| 233 | |||
| 234 | =cut | ||
| 235 | |||
| 236 | sub parse_query_result { | ||
| 237 | my ( $self, $content ) = @_; | ||
| 238 | my $desc; | ||
| 239 | eval { | ||
| 240 | XML::Twig->new( | ||
| 241 | 'TwigHandlers' => { | ||
| 242 | 'channel' => sub { | ||
| 243 | $desc = $rss_handler->('create_description',$self,@_); | ||
| 244 | }, | ||
| 245 | 'item' => sub { | ||
| 246 | my $res = $rss_handler->('create_resource',$self,@_); | ||
| 247 | $desc->insert($res); | ||
| 248 | }, | ||
| 249 | } | ||
| 250 | )->parse($content); | ||
| 251 | }; | ||
| 252 | return $desc; | ||
| 253 | } | ||
| 254 | |||
| 255 | =item get_record() | ||
| 256 | |||
| 257 | Gets a PhyloWS database record | ||
| 258 | |||
| 259 | Type : Accessor | ||
| 260 | Title : get_record | ||
| 261 | Usage : my $rec = $obj->get_record( -guid => $guid ); | ||
| 262 | Function: Gets a PhyloWS database record | ||
| 263 | Returns : Bio::Phylo::Project object | ||
| 264 | Args : Required: -guid => $guid | ||
| 265 | |||
| 266 | =cut | ||
| 267 | |||
| 268 | sub get_record { | ||
| 269 | my $self = shift; | ||
| 270 | if ( my %args = looks_like_hash @_ ) { | ||
| 271 | $self->set_guid( $args{'-guid'} || throw 'BadArgs' => "Need -guid argument" ); | ||
| 272 | $self->set_query(); | ||
| 273 | my $url = $self->get_url( '-format' => 'nexml' ); | ||
| 274 | $logger->debug($url); | ||
| 275 | return parse( | ||
| 276 | '-format' => 'nexml', | ||
| 277 | '-url' => $url, | ||
| 278 | '-as_project' => 1, | ||
| 279 | ); | ||
| 280 | } | ||
| 281 | } | ||
| 282 | |||
| 283 | =item get_ua() | ||
| 284 | |||
| 285 | Gets the underlying L<LWP::UserAgent> object that the client uses to communicate with the service | ||
| 286 | |||
| 287 | Type : Accessor | ||
| 288 | Title : get_ua | ||
| 289 | Usage : my $ua = $obj->get_ua; | ||
| 290 | Function: Gets user agent | ||
| 291 | Returns : LWP::UserAgent object | ||
| 292 | Args : None | ||
| 293 | |||
| 294 | =cut | ||
| 295 | |||
| 296 | sub get_ua { $ua{ shift->get_id } } | ||
| 297 | |||
| 298 | sub _cleanup { | ||
| 299 | my $self = shift; | ||
| 300 | my $id = $self->get_id; | ||
| 301 | for my $field (@fields) { | ||
| 302 | delete $field->{$id}; | ||
| 303 | } | ||
| 304 | } | ||
| 305 | |||
| 306 | =back | ||
| 307 | |||
| 308 | =cut | ||
| 309 | |||
| 310 | # podinherit_insert_token | ||
| 311 | |||
| 312 | =head1 SEE ALSO | ||
| 313 | |||
| 314 | There is a mailing list at L<https://groups.google.com/forum/#!forum/bio-phylo> | ||
| 315 | for any user or developer questions and discussions. | ||
| 316 | |||
| 317 | Also see the manual: L<Bio::Phylo::Manual> and L<http://rutgervos.blogspot.com> | ||
| 318 | |||
| 319 | =head1 CITATION | ||
| 320 | |||
| 321 | If you use Bio::Phylo in published research, please cite it: | ||
| 322 | |||
| 323 | B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen> | ||
| 324 | and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl. | ||
| 325 | I<BMC Bioinformatics> B<12>:63. | ||
| 326 | L<http://dx.doi.org/10.1186/1471-2105-12-63> | ||
| 327 | |||
| 328 | =cut | ||
| 329 | |||
| 330 | } | ||
| 331 | 1; |