Audioscrobbler/DataFetcher.pm

filter: Statementstmt 46.9% 23 / 49 Branchbran 0.0% 0 / 14 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 54.5% 6 / 11 Podpod 100% 5 / 5 totaltotal 43.0% 34 / 79 CC 8 SCAR 23.8
CC
8
Cov
37%
new
30.0
fetch
6.0
retrieve_data
6.0
CRAP 10.8
« Audioscrobbler/User.pm ↑ Summary Audioscrobbler/Tag.pm »
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
BranchTrueFalseTotal
ref $base_or_params eq 'HASH' ? : 0 0 0
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
BranchTrueFalseTotal
unless defined $self->base_url 0 0 0
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
BranchTrueFalseTotal
unless $self->base_url->isa("URI") 0 0 0
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
BranchTrueFalseTotal
unless $self->cache 0 0 0
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
BranchTrueFalseTotal
unless (defined $data) 0 0 0
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
BranchTrueFalseTotal
my $resp = &LWP::Simple::get($uri) or $self->croak("Error while fetching data from '${uri}'") 0 0 0
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
BranchTrueFalseTotal
if $_[0]->isa(&CLASS()) 0 0 0
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
« Audioscrobbler/User.pm ↑ Summary Audioscrobbler/Tag.pm »