rubyweather 1.0.0 → 1.1.0

data/README

@@ -6,7 +6,29 @@ License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
 
 <b>RubyWeather is a Ruby[http://ruby-lang.org] library for fetching weather-related data from weather.com[http://www.weather.com/services/xmloap.html].</b>
 
-Simple usage example:
+
+=== Download & Install
+
+You can download the latest stable version of RubyWeather from http://rubyforge.org/projects/rubyweather
+or install as a RubyGem:
+
+  sudo gem install rubyweather
+
+You can also check out the latest copy via subversion from svn://rubyforge.org//var/svn/rubyweather/trunk.
+If you would like to contribute back your changes to the code, please contact me via the rubyforge project 
+site to obtain a subversion account.
+
+RubyWeather can also be installed as a Rails plugin using the following command from your Rails application's
+directory:
+
+  ./script/plugin install -x svn://rubyforge.org//var/svn/rubyweather/trunk
+
+
+=== Examples
+
+First, we need to find out the weather.com location code for your city.
+This will print out a list of locations and their codes matching the 
+string "Toronto":
 
   require 'rubygems'
   require_gem 'rubyweather'
@@ -20,8 +42,7 @@ Simple usage example:
   locations = service.find_location('Toronto')
   puts "Matching Locations: " + locations.inspect
 
-The above will print out a list of available locations and their codes. We can
-now use these codes to fetch the weather data for our city:
+We can now use the code to fetch the weather data for our city:
 
   forecast = service.fetch_forecast("CAXX0504", 5)
 
@@ -34,13 +55,17 @@ now use these codes to fetch the weather data for our city:
   puts "Tomorrow's Outlook: %s" % forecast.tomorrow.outlook
   puts "Tomorrow's Wind Direction: %s" % forecast.tomorrow.wind.direction
 
-Forecasts for days in the future are accessed via <tt>forecast.day(#)</tt> where <tt>#</tt> is the number of day sinto the future
+Forecasts for days in the future are accessed via <tt>forecast.day(#)</tt> where <tt>#</tt> is the number of days into the future
 (assuming that you've fetched data for as many days in your <tt>service.fetch_forecast</tt> request):
 
   puts "High 3 days from now: %s" % forecast.day(3).high
   puts "Probability of precipitation 4 days from now: %s" % forecast.day(4).pop
 
-There are a lot of attributes you can fetch for a forecast day. Here are just a few:
+Nighttime data is also available via <tt>forecast.night(#)</tt>:
+
+  puts "Probability of precipitation three nights from now: %s" % forecast.night(3).pop
+
+There are a lot of attributes you can fetch for a forecast. Here are just a few:
 
 +temp+, +temperature+:: The temperature. For future days this is equivalent to the low for nighttime, and high for daytime.
 +icon+:: The number of the icon gif file from the weather.com SDK[http://www.weather.com/services/xmloap.html] that
@@ -58,29 +83,40 @@ There are a lot of attributes you can fetch for a forecast day. Here are just a
 +latest_update+:: The datetime when the conditions were last measured/forecast.
 
 Additionally, most of the attributes for a given day in the raw weather.com xml data are
-also directly accessible. For example, you can call forecast.tomorrow.dewp to get the dewpoint, because the xml file
-contains a <tt>dewp</tt> element for that day. Have a look at #test/test_weather.xml to see what data is
+also directly accessible. For example, you can call <tt>forecast.tomorrow.dewp</tt> to get the dewpoint, because the xml file
+contains a <tt>dewp</tt> element for that day. Have a look at <tt>test/test_weather.xml</tt> to see what data is
 available in the xml file. Note though that raw xml elements will be returned as a string, without any nice
 class casting or unit conversion.
 
-Other programmers are encouraged to add more functionality to the lib/forecast.rb module to provide better
+Other programmers are encouraged to add more functionality to the <tt>lib/forecast.rb</tt> module to provide better
 accessor methods for the underlying xml data. See below for how to obtain subversion access to contribute
 your changes back to the project.
 
-== Download
+=== Caching Forecast Data
 
-You can download the latest stable version of RubyWeather from http://rubyforge.org/projects/rubyweather/.
+RubyWeather supports data caching using the memcached[http://www.danga.com/memcached/] daemon. This allows for
+much quicker response time -- especially if you have a lot of clients accessing the weather data -- and is 
+just a polite thing to do in regards weather.com's servers.
+If you have a memcached server running, you can turn on data caching as follows:
 
-You can also check out the latest copy via subversion from svn://rubyforge.org//var/svn/rubyweather/trunk.
-If you would like to contribute back your changes to the code, please contact me via the rubyforge project 
-site to obtain a subversion account.
+  s = Weather::Service.new
+  s.enable_cache
+  s.cache_expiry = 60  # cached data will expire after 60 seconds; if omitted, the default is 10 minutes
+  s.cache.servers = ['127.0.0.1:11211']
+  
+From now on, any fetch_forecast calls made on this service will cache their data. This means that the weather.com
+server will not be queried again as long as the data is cached.
 
-RubyWeather can also be installed as a Rails plugin using the following command from your Rails application's
-directory:
+You can check if a forecast came from the cache by calling <tt>#from_cache?</tt>, which returns true if this
+forecast came from the local cache, or <tt>#cached_on</tt>, which returns the datetime when this forecast was
+entered into the cache or nil if the forecast didn't come from the cache.
 
-  ./script/plugin install -x svn://rubyforge.org//var/svn/rubyweather/trunk
+The above requires that a ruby memcache client be installed. RubyWeather has been tested with the 
+Ruby-MemCache[http://www.deveiate.org/projects/RMemCache] implementation which you can install using:
+
+  gem install Ruby-MemCache
 
-== Sample Rails Controller
+=== Sample Rails Controller
 
 In the <tt>example</tt> directory you will find a sample Rails controller that uses RubyWeather to show
 a simple weather forecast. To try this out:

data/lib/weather/forecast.rb

@@ -14,8 +14,11 @@ module Weather
   
     # Contains several days of weather data.
     # The forecast object includes the Enumerable mixin, so that you can iterate
-    # over all of the days in the forecast using the standard ruby mechanisms
-    # (i.e. <tt>myforecast.each { |d| print d.outlook }</tt>).
+    # over all of the days in the forecast using the standard ruby mechanisms as follows:
+    #   
+    #   myforecast.each do |d|
+    #     print d.outlook
+    #   end
     class Forecast      
       include Enumerable
       
@@ -29,9 +32,12 @@ module Weather
         
         @xml = weather_xmldoc
         
-        # add the lsup (latest update) element to individual days to make parsing easier later on
+        # add the lsup (latest update) and cached_on elements to individual days to make parsing easier later on
         # FIXME: I can't seem to add the lsup as an element (which would be the consistent way to do it)... adding it as an attribute seems to work though
-        lsup = @xml.root.elements['dayf'].elements['lsup'].text
+        if @xml.root.elements['dayf'] and @xml.root.elements['dayf'].elements['lsup']
+          lsup = @xml.root.elements['dayf'].elements['lsup'].text
+        end
+        
         REXML::XPath.match(@xml, "//dayf/day").each do |dxml|
           dxml.add_attribute "lsup", lsup
         end
@@ -121,9 +127,25 @@ module Weather
       def latest_update
         Time.parse(xml.root.elements['dayf'].elements['lsup'].text)
       end
+      
+      # The date and time when this forecast was last locally cached.
+      # This attribute will be nil when the forecast comes directly from the weather.com
+      # server or when you do not have the local cache enabled.
+      # See Weather::Service#enable_cache and also the README for instructions on
+      # how to enable local caching using memcached.
+      def cached_on
+        cached_on = xml.root.attributes['cached_on']
+        Time.parse(cached_on) if cached_on 
+      end
+      
+      # True if this forecast came from the local cache; false otherwise.
+      # See Weather::Forecast.cached_on and Weather::Service#enable_cache.
+      def from_cache?
+        not cached_on.nil?
+      end
     end
     
-    # Abstract class that all Forecast entities (roughly "days") are based on.
+    # Abstract class that all Forecast entities are based on.
     class Conditions
     
       # For elements in the forecast that we have not defined an explicit accessor,

data/lib/weather/service.rb

@@ -48,7 +48,17 @@ module Weather
       
       # puts "Using url: "+url
       
-      xml = Net::HTTP.get(host, url);
+      if cache? and xml = cache.get("#{location_id}:#{days}")
+      else
+        xml = Net::HTTP.get(host, url)
+        
+        if cache?
+          doc = REXML::Document.new(xml)
+          doc.root.attributes['cached_on'] = Time.now 
+          cache.set("#{location_id}:#{days}", doc.to_s, cache_expiry)
+        end
+      end
+      
       doc = REXML::Document.new(xml)
 
       Forecast::Forecast.new(doc)
@@ -80,5 +90,66 @@ module Weather
       
       return locations
     end
+    
+    
+    @cache = false
+    
+    # Turns on weather forecast caching.
+    # See Weather::Service::Cache
+    def enable_cache(enable = true)
+      if enable
+        extend Cache
+        @cache = true
+      else
+        @cache = false
+      end
+    end
+    
+    # True if caching is enabled, false otherwise.
+    def cache?
+      @cache and cache.active?
+    end
+    
+    # Turns off weather forecast caching.
+    # See Weather::Service::Cache
+    def disable_cache
+      enable_cache false
+    end
+    
+    # Memcache functionality for Weather::Service.
+    # This is automatically mixed in when you call Weather::Service#enable_cache
+    module Cache
+  
+      # The MemCache client instance currently being used.
+      # To set the memcache servers, use:
+      # 
+      #   service.cache.servers = ["127.0.0.1:11211"]
+      def cache
+        @memcache ||= MemCache.new(:namespace => 'RubyWeather')
+      end
+      
+      # Sets how long forecast data should be cached (in seconds).
+      def cache_expiry=(seconds)
+        @cache_expiry = seconds
+      end
+      # The current cache_expiry setting, in seconds.
+      def cache_expiry
+        @cache_expiry || 60 * 10
+      end
+      
+      private
+        def self.extend_object(o)
+          begin
+            require 'memcache'
+          rescue LoadError
+            require 'rubygems'
+            # We use Ruby-MemCache because it works. Despite my best efforts, I 
+            # couldn't get the memcache-client implementation working properly.
+            require_gem 'Ruby-MemCache'
+            require 'memcache'
+          end
+          super
+        end
+    end
   end
 end

data/test/service_test.rb

@@ -59,4 +59,27 @@ class ServiceTest < Test::Unit::TestCase
     locations = @service.find_location("Toronto")
     assert(locations.has_key?(TEST_LOCATION))
   end
+  
+  def test_caching
+    # This assumes that we have a memcache server running on localhost:11211!
+    @service.enable_cache
+    @service.cache.servers = "localhost:11211"
+    
+    @service.cache.delete("#{TEST_LOCATION}:5")
+    
+    assert_equal @service.fetch_forecast(TEST_LOCATION, 5).xml.to_s, @service.fetch_forecast(TEST_LOCATION, 5).xml.to_s.gsub(/ cached_on='.*?'/, '')
+    
+    assert @service.fetch_forecast(TEST_LOCATION, 5).from_cache?
+    
+    xml = @service.cache.get("#{TEST_LOCATION}:5")
+    assert xml and !xml.empty?
+    
+    @service.cache_expiry = 1
+    
+    @service.fetch_forecast(TEST_LOCATION, 2)
+    sleep(2)
+    assert_nil @service.cache.get("#{TEST_LOCATION}:2")
+    
+    assert !@service.fetch_forecast(TEST_LOCATION, 2).from_cache?
+  end
 end

metadata

@@ -3,7 +3,7 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: rubyweather
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.1.0
 date: 2006-07-28 00:00:00 -04:00
 summary: Client library for accessing weather.com's xoap weather data.
 require_paths: 
@@ -98,7 +98,7 @@ test_files:
 - test/service_test.rb
 rdoc_options: 
 - --title
-- RubyWeather RDocs
+- RubyWeather 1.1.0 RDocs
 - --main
 - README
 - --line-numbers