| 1 | package WebService::Audioscrobbler::DataFetcher; | ||||||||||
| 2 | 2 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 3 | 2 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | 2 | ▶ | use CLASS; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 5 | 2 | ▶ | use base 'Class::Accessor::Fast'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 6 | |||||||||||
| 7 | 2 | ▶ | use Cache::FileCache; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 8 | 2 | ▶ | use URI; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 9 | |||||||||||
| 10 | 2 | require LWP::Simple; | |||||||||
| 11 | 2 | require XML::Simple; | |||||||||
| 12 | |||||||||||
| 13 | =head1 NAME | ||||||||||
| 14 | |||||||||||
| 15 | WebService::Audioscrobbler::DataFetcher - Cached data fetching provider | ||||||||||
| 16 | |||||||||||
| 17 | =cut | ||||||||||
| 18 | |||||||||||
| 19 | 2 | our $VERSION = '0.07'; | |||||||||
| 20 | |||||||||||
| 21 | # object accessors | ||||||||||
| 22 | 2 | CLASS->mk_accessors(qw/base_url cache_root cache/); | |||||||||
| 23 | |||||||||||
| 24 | =head1 SYNOPSIS | ||||||||||
| 25 | |||||||||||
| 26 | This is responsible for fetching and caching all data requested from Audioscrobbler | ||||||||||
| 27 | WebServices, as recommended by their usage policy. | ||||||||||
| 28 | |||||||||||
| 29 | It can actually function as a generic XML-fetcher-and-converter-to-hashrefs and has | ||||||||||
| 30 | no limitations regarding being used only for Audioscrobbler WebServices. In the future, | ||||||||||
| 31 | it might even became a completely separate module. | ||||||||||
| 32 | |||||||||||
| 33 | use WebService::Audioscrobbler::DataFetcher; | ||||||||||
| 34 | |||||||||||
| 35 | my $data_fetcher = WebService::Audioscrobbler::DataFetcher->new( | ||||||||||
| 36 | "http://www.my-base-url.com/base_dir/" | ||||||||||
| 37 | ); | ||||||||||
| 38 | |||||||||||
| 39 | # retrieves "http://www.my-base-url.com/base_dir/myown/resource.xml" | ||||||||||
| 40 | # and parses it through XML::Simple::XMLin so we get a hashref | ||||||||||
| 41 | my $data = $data_fetcher->fetch("myown/resource.xml") | ||||||||||
| 42 | |||||||||||
| 43 | =cut | ||||||||||
| 44 | |||||||||||
| 45 | =head1 FIELDS | ||||||||||
| 46 | |||||||||||
| 47 | =head2 C<base_url> | ||||||||||
| 48 | |||||||||||
| 49 | This is the base URL from where data will be fetched. | ||||||||||
| 50 | |||||||||||
| 51 | =head2 C<cache> | ||||||||||
| 52 | |||||||||||
| 53 | This is the underlying cache object. By default, this will be a | ||||||||||
| 54 | L<Cache::FileCache> object. | ||||||||||
| 55 | |||||||||||
| 56 | =head2 C<cache_root> | ||||||||||
| 57 | |||||||||||
| 58 | This is the root directory where the cache will be created. It should only be | ||||||||||
| 59 | set as a parameter to C<new()>, setting it afterwards won't have any effect. | ||||||||||
| 60 | |||||||||||
| 61 | =cut | ||||||||||
| 62 | |||||||||||
| 63 | =head1 METHODS | ||||||||||
| 64 | |||||||||||
| 65 | =cut | ||||||||||
| 66 | |||||||||||
| 67 | =head2 C<new($base_url)> | ||||||||||
| 68 | |||||||||||
| 69 | =head2 C<new(\%fields)> | ||||||||||
| 70 | |||||||||||
| 71 | Creates a new object using either the given C<$base_url> or the C<\%fields> | ||||||||||
| 72 | hashref. Any of the above fields can be specified. If the C<cache> field is | ||||||||||
| 73 | undefined, C<create_cache> will be called after object construction. | ||||||||||
| 74 | |||||||||||
| 75 | =cut | ||||||||||
| 76 | |||||||||||
| 77 | sub new { | ||||||||||
| 78 | 0 | ▶ | my $class = shift; | ||||||||
|
Subroutine
new: not called CC=5 SCAR=34.0
Pod
documented
| |||||||||||
| 79 | 0 | my $base_or_params = shift; | |||||||||
| 80 | |||||||||||
| 81 | 0 | ▶ | my $self = $class->SUPER::new( | ||||||||
|
Branch: 1 branch
| |||||||||||
| 82 | ref $base_or_params eq 'HASH' ? $base_or_params : { base_url => $base_or_params } | ||||||||||
| 83 | ); | ||||||||||
| 84 | |||||||||||
| 85 | # base_url is mandatory | ||||||||||
| 86 | 0 | ▶ | $self->croak("base_url not set") | ||||||||
|
Branch: 1 branch
| |||||||||||
| 87 | unless defined $self->base_url; | ||||||||||
| 88 | |||||||||||
| 89 | # guarantee it's an URI object | ||||||||||
| 90 | 0 | ▶ | $self->base_url(URI->new($self->base_url)) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 91 | unless $self->base_url->isa('URI'); | ||||||||||
| 92 | |||||||||||
| 93 | # crate a new cache object, unless we're already given one | ||||||||||
| 94 | 0 | ▶ | $self->create_cache unless $self->cache; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 95 | |||||||||||
| 96 | 0 | return $self; | |||||||||
| 97 | } | ||||||||||
| 98 | |||||||||||
| 99 | =head2 C<create_cache> | ||||||||||
| 100 | |||||||||||
| 101 | Creates a new L<Cache::FileCache> object and saves it in the C<cache> field. | ||||||||||
| 102 | The cache has a daily auto purging turned on and data will expire by default | ||||||||||
| 103 | in 3 days, which is reasonable since most of Audioscrobbler data changes at | ||||||||||
| 104 | most weekly. The cache root will be as specified by the C<cache_root> field | ||||||||||
| 105 | (if it's undefined, L<Cache::FileCache> defaults will be used). | ||||||||||
| 106 | |||||||||||
| 107 | =cut | ||||||||||
| 108 | |||||||||||
| 109 | sub create_cache { | ||||||||||
| 110 | 0 | ▶ | my $self = shift; | ||||||||
|
Subroutine
create_cache: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 111 | 0 | $self->cache( | |||||||||
| 112 | Cache::FileCache->new( { | ||||||||||
| 113 | auto_purge_on_set => 1, | ||||||||||
| 114 | auto_purge_interval => 86400, # 1 day | ||||||||||
| 115 | default_expires_in => 259200, # 3 days | ||||||||||
| 116 | cache_root => $self->cache_root | ||||||||||
| 117 | } ) | ||||||||||
| 118 | ) | ||||||||||
| 119 | } | ||||||||||
| 120 | |||||||||||
| 121 | =head2 C<fetch($resource)> | ||||||||||
| 122 | |||||||||||
| 123 | Actually fetches a XML resource URL. If the resource is not already cached, | ||||||||||
| 124 | C<retrieve_data> is called it's results are then cached. The results are then | ||||||||||
| 125 | processed by C<XML::Simple::XMLin> so we end up with a nice hashref as our | ||||||||||
| 126 | return value. | ||||||||||
| 127 | |||||||||||
| 128 | =cut | ||||||||||
| 129 | |||||||||||
| 130 | sub fetch { | ||||||||||
| 131 | 0 | ▶ | my ($self, $resource) = @_; | ||||||||
|
Subroutine
fetch: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 132 | |||||||||||
| 133 | # build and normalize the URL | ||||||||||
| 134 | 0 | my $uri = $self->base_url->clone; | |||||||||
| 135 | 0 | $uri->path_segments(grep {length} $uri->path_segments, split '/', $resource); | |||||||||
| 136 | |||||||||||
| 137 | # try to fetch a cached copy of the data | ||||||||||
| 138 | 0 | my $data = $self->cache->get($uri); | |||||||||
| 139 | |||||||||||
| 140 | # not in cache | ||||||||||
| 141 | 0 | ▶ | unless (defined $data) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 142 | 0 | my $resp = $self->retrieve_data($uri); | |||||||||
| 143 | |||||||||||
| 144 | # parse it into a hashref | ||||||||||
| 145 | 0 | $data = XML::Simple::XMLin($resp); | |||||||||
| 146 | |||||||||||
| 147 | # cache it for future references | ||||||||||
| 148 | 0 | $self->cache->set($uri, $data); | |||||||||
| 149 | } | ||||||||||
| 150 | |||||||||||
| 151 | 0 | return $data; | |||||||||
| 152 | |||||||||||
| 153 | } | ||||||||||
| 154 | |||||||||||
| 155 | =head2 C<retrieve_data($uri)> | ||||||||||
| 156 | |||||||||||
| 157 | Retrieves data from the specified $uri using L<LWP::Simple> and returns it. | ||||||||||
| 158 | |||||||||||
| 159 | =cut | ||||||||||
| 160 | |||||||||||
| 161 | sub retrieve_data { | ||||||||||
| 162 | 0 | ▶ | my ($self, $uri) = @_; | ||||||||
|
Subroutine
retrieve_data: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 163 | |||||||||||
| 164 | # warn "\nRetrieving data from $uri...\n"; | ||||||||||
| 165 | |||||||||||
| 166 | 0 | ▶ | my $resp = LWP::Simple::get($uri) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 167 | or $self->croak("Error while fetching data from '$uri'"); | ||||||||||
| 168 | |||||||||||
| 169 | 0 | utf8::upgrade($resp); | |||||||||
| 170 | |||||||||||
| 171 | 0 | return $resp; | |||||||||
| 172 | } | ||||||||||
| 173 | |||||||||||
| 174 | =head2 C<croak> | ||||||||||
| 175 | |||||||||||
| 176 | Shortcut for C<Carp::croak> which can be called as a method. | ||||||||||
| 177 | |||||||||||
| 178 | =cut | ||||||||||
| 179 | |||||||||||
| 180 | sub croak { | ||||||||||
| 181 | 0 | ▶ | shift if $_[0]->isa(CLASS); | ||||||||
|
Subroutine
croak: not called CC=2 SCAR=17.9
Pod
documented
Branch: 1 branch
| |||||||||||
| 182 | 0 | require Carp; | |||||||||
| 183 | 0 | Carp::croak(@_); | |||||||||
| 184 | } | ||||||||||
| 185 | |||||||||||
| 186 | =head1 AUTHOR | ||||||||||
| 187 | |||||||||||
| 188 | Nilson Santos Figueiredo Júnior, C<< <nilsonsfj at cpan.org> >> | ||||||||||
| 189 | |||||||||||
| 190 | =head1 COPYRIGHT & LICENSE | ||||||||||
| 191 | |||||||||||
| 192 | Copyright 2006-2007 Nilson Santos Figueiredo Júnior, all rights reserved. | ||||||||||
| 193 | |||||||||||
| 194 | This program is free software; you can redistribute it and/or modify it | ||||||||||
| 195 | under the same terms as Perl itself. | ||||||||||
| 196 | |||||||||||
| 197 | =cut | ||||||||||
| 198 | |||||||||||
| 199 | 2 | 1; # End of WebService::Audioscrobbler::DataFetcher | |||||||||