XML::RSS::Timing - understanding RSS skipHours, skipDays, sy:update*
...after getting an RSS/RDF feed that contains the following: <sy:updateFrequency>3</sy:updateFrequency> <sy:updatePeriod>hourly</sy:updatePeriod> <sy:updateBase>1970-01-01T08:20+00:00</sy:updateBase> use XML::RSS::Timing; my $timing = XML::RSS::Timing->new; $timing->lastPolled( time() ); $timing->updatePeriod( 'hourly' ); $timing->updateFrequency( 3 ); $timing->updateBase( '1970-01-01T08:20+00:00' ); # Find out the soonest I can expect new content: my $then = $timing->nextUpdate; print "I can next poll the feed after $then (", scalar(localtime($then)), " local time)\n";
Polling it before $then is unlikely to return any new content, according to the sy:update* elements' values.
$then
sy:update*
RSS/RDF modules can use the elements skipHours, skipDays, ttl, sy:updateBase, sy:updatePeriod, and sy:updateFrequency to express what days/times they won't update, so that RSS/RDF clients can conserve network resources by not bothering to poll a feed more than once during such a period.
skipHours
skipDays
ttl
sy:updateBase
sy:updatePeriod
sy:updateFrequency
This Perl module is for taking in the RSS/RDF skipHours, skipDays, ttl, and sy:update* elements' values, and figuring out when they say new content might be available.
Note: This module doesn't depend on XML::RSS, nor in fact have any particular relationship with it.
There are two perspectives on this problem:
With this perspective, you have just polled the given RSS/RDF feed (regardless of whether its content turns out to be new), and you want to see if the feed says you can skip polling it until some other future time. With this perspective, you extract the sy:update* fields' values and/or the skipHours, skipDays, and ttl values and pass them to a new XML::RSS::Timing object, and then ask when you should avoid polling this until. And in the end you'll probably do this:
my $wait_until = $timing->nextUpdate; $wait_until = time() + $Default_Polling_Delay # where $Default_Polling_Delay is some reader-defined value if $wait_until <= time();
...and then file away $wait_until's value in some internal table that is consulted before polling things, like so:
$wait_until
foreach my $feed (@FeedObjects) { next if $feed->wait_until > time(); # Don't poll it, there'll be nothing new ...Else go ahead and poll it, there could be something new... }
With this perspective, you polled the RSS feed at some time in the past, and are now considering whether its sy:update* fields' values and/or the skip* and ttl values (which you stored somewhere) say you can now poll the feed (or whether there'd be no point, if the skip*/update* fields say you shouldn't expect any new content). With this perspective, you use code like this:
skip*
skip*/update*
...after calling ->skipHours and/or ->updatePeriod, etc $timing->lastPolled( $when_last_polled ); if( time() < $timing->nextUpdate ) { # ...Don't poll it, there'll be nothing new... } else { ... go ahead and poll it, there could be something new... }
Of the two perspectives, this second one seems less efficient to me, but your mileage may vary.
This class defines the following methods:
$timing = XML::RSS::Timing->new();
This constructor method creates a new object to be used on figuring feed timing. You should use a new object for each feed you're considering.
$timing->skipHours( hournum, hournum... )
This adds to this $timing object the given list of hours from the given feed's skipHours element. Hours are expressed as integers between 0 to 23 inclusive.
$timing
$timing->skipDays( dayname, dayname... )
This adds to this $timing object the given list of days from the given feed's skipDays element. The day name strings have to be from the set: "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday".
$timing->updateFrequency( integer )
This sets the given $timing object's updateFrequency value from the feed's (optional) sy:updateFrequency element. This has to be a nonzero positive integer.
$timing->updateBase( iso_time )
This sets the given $timing object's updateFrequency value from the feed's (optional) sy:updateFrequency element. This has to be a date in one of these formats:
1997 1997-07 1997-07-16 1997-07-16T19:20 1997-07-16T19:20Z 1997-07-16T19:20+01:00 1997-07-16T19:20:30+01:00 1997-07-16T19:20:30.45+01:00
The default value is "1970-01-01T00:00Z".
$timing->updatePeriod( periodname )
This sets the given $timing object's updatePeriod value from the feed's (optional) sy:updatePeriod element. This has to be a string from the set: "hourly", "daily", "weekly", "monthly", "yearly".
$timing->lastPolled( epoch_time )
This sets the time when you last polled this feed. If you don't set this, the current time (time()) will be used.
time()
Note that by "polling", I mean not just requesting the feed, but requesting the feed and getting a successful response (regardless of whether it's an HTTP 200 "OK" response or an HTTP 304 "Not Modified" response). If you request a feed and get any sort of error, then don't count that as actually polling the feed.
$timing->ttl( integer )
This sets the given $timing object's "ttl" value from the feed's (optional) ttl element. This has to be a nonzero positive integer. It represents the minimum number of minutes that a reader can go between times it polls the given feed. It is a somewhat obsolescent (but common) predecessor to the sy:update* fields.
("TTL" stands for "time to live", a term borrowed from DNS cache jargon.)
$timing->maxAge( integer )
This sets the given $timing object's "maxAge" value. This has to be a nonzero positive integer.
This value comes not from the feed, but is an (optional) attribute of your client: it denotes the maximum amount of time (in seconds) that your client will go between polling, overriding whatever this feed says.
For example, if a feed says it updates only once a year, minAge is a two months, then this timing object will act as if the feed really said to update every two months.
minAge
If you set this, you should probably set it only to a large value, like the number of seconds in two months (62*24*60*60). By default, this is not set, meaning no maximum is enforced. (So if a feed says to update only once a year, then that's what this timing object faithfully implements.)
$timing->minAge( integer )
This sets the given $timing object's "minAge" value. This has to be a nonzero positive integer.
This value comes not from the feed, but is an (optional) attribute of your client: it denotes the minimum amount of time (in seconds) that your client will go between polling, overriding whatever this feed says.
For example, if a feed says it can update every 5 minutes, but your minAge is a half hour, then this timing object will act as if the feed really said to update only half hour at most.
If you set minAge, you should probably set it only to a smallish value, like the number of seconds in an hour (60*60). By default, this is not set, meaning no minimum is enforced.
$epochtime = $timing->nextUpdate();
This method returns the time (in seconds since the epoch) that's the soonest that this feed could return new content.
Note that this doesn't mean you have to actually poll the feed right at that second! (That's why this is called "nextUpdate", not something like "nextPoll".) Instead, I presume your RSS-reader will do something like
run at random intervals and will just look for what feeds' nextUpdate times are less than time() .)
Note that nextUpdate might return the same as this feed's lastPolled value, in the case of a feed without any ttl/sy:*/update* information and where you haven't specified a minAge.
nextUpdate
lastPolled
$timing->use_exceptions( 0 )
$timing->use_exceptions( 1 )
This sets whether this object will (with a 1) or won't (with a 0) use exceptions (die's) to signal errors, or whether it will simply muddle through and collect them in complaints.
die
complaints
Basically, errors can come from passing invalid parameters to this module's methods, such as passing "friday" to skipDays (instead of "Friday"), or passing 123 to skipHours (instead of an integer in the range 0-23), etc.
By default, use_exceptions is on.
@complaints = $timing->complaints()
This returns a list of any errors that were encountered in dealing with this $timing object. Errors can result from blocking exceptions (if use_exceptions is off), or from non-fatal warnings of interest while debugging (like if skipHours was told to skip all 24 hours).
use_exceptions
If there were no complaints, this will simply return an empty list.
Because of currently common limitations on the size of integers used in reckoning dates, this module cannot process dates (whether as current time, or as updateBase time) before the year 1902 or after the year 2037. This is merely an implementational limitation, not something inherent to the RSS/RDF specs.
Although the spec places no such limit, this implementation requires the updateBase's date to be between 1902 and 2038 (noninclusive).
The Perl modules XML::RSS , XML::RSS::SimpleGen , XML::RSS::Parser , XML::RSS::SimpleGen , XML::RSS::Tools
http://blogs.law.harvard.edu/tech/rss
http://web.resource.org/rss/1.0/modules/syndication/
http://groups.yahoo.com/group/rss-dev/
http://feedvalidator.org/
Sean M. Burke, <sburke@cpan.org>, with the helpful consultation of the RSS-DEV group.
Copyright (c) 2004, Sean M. Burke. All rights reserved.
This library is free software; you can redistribute it and/or modify it only under the terms of version 2 of the GNU General Public License (perlgpl).
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
(But if you have any problems with this library, I ask that you let me know.)
Sean M. Burke <sburke@cpan.org>
To install XML::RSS::Timing, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XML::RSS::Timing
CPAN shell
perl -MCPAN -e shell install XML::RSS::Timing
For more information on module installation, please visit the detailed CPAN module installation guide.