rcap 0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1 - 5th November 2009
+ * Initial release

data/README

@@ -0,0 +1,151 @@
+= RCAP - Common Alerting Protocol for Ruby
+
+== Overview
+
+The Common Alerting Protocol is a lightweight standard to facilitate the distribution of alerting data. RCAP is an implementation of the CAP in Ruby. It allows for the creation of RCAP messages from Ruby applications and the parsing of external messages.
+
+RCAP supports CAP Version 1.1.
+
+== Usage
+
+To include RCAP into your application add the following require
+
+ require 'rcap/rcap'
+
+=== Creating an Alert
+
+==== From XML
+
+RCAP allows for the parsing of a CAP XML string into a collection of RCAP objects
+
+ alert = RCAP::Alert.from_xml( xml_string )
+
+Currently RCAP only supports version 1.1 of the CAP standard and the parser is as strict as possible when parsing data.
+
+==== Programatically
+
+Alerts can also be created programatically by initialising the various RCAP classes manually
+
+ include RCAP # Include RCAP module into namespace
+
+ alert = Alert.new( :sender   => 'cape_town_disaster_relief@capetown.municipal.za',
+                    :status   => Alert::STATUS_ACTUAL, 
+                    :msg_type => Alert::MSG_TYPE_ALERT,
+                    :scope    => Alert::SCOPE_PUBLIC,  
+                    :infos    => Info.new( :event       => 'Liquid Petroleoum Tanker Fire',
+                                           :language    => 'en-ZA',
+                                           :categories  => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
+                                           :urgency     => Info::URGENCY_IMMEDIATE,
+                                           :severity    => Info::SEVERITY_SEVERE,
+                                           :certainty   => Info::CERTAINTY_OBSERVED,
+                                           :headline    => 'LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY',
+                                           :description => 'A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+                                                           after the R300 interchange.  Municipal fire fighting crews have been dispatched.
+                                                           Traffic control officers are on the scene and have diverted traffic onto 
+                                                           alternate routes.' ))
+
+ # Accessing attributes
+ puts alert.status                          # Print out "Actual"
+ puts alert.infos[0].language               # Print out "en-ZA"
+ puts alert.infos[0].categories.join( ' ' ) # Print out "Transport Fire"
+
+ puts alert.to_xml # Print out CAP XML message
+
+Will print the following CAP XML
+
+  <?xml version='1.0'?>
+  <alert xmlns='urn:oasis:names:tc:emergency:cap:1.1'>
+    <identifier>494207a7-f86b-4060-8318-a4b2a3ce565e</identifier>
+    <sender>cape_town_disaster_relief@capetown.municipal.za</sender>
+    <sent>2009-10-26T21:04:51+2:00</sent>
+    <status>Actual</status>
+    <msgType>Alert</msgType>
+    <scope>Public</scope>
+    <info>
+      <language>en-ZA</language>
+      <category>Transport</category>
+      <category>Fire</category>
+      <event>Liquid Petroleoum Tanker Fire</event>
+      <urgency>Immediate</urgency>
+      <severity>Severe</severity>
+      <certainty>Observed</certainty>
+      <headline>LIQUID PETROLEOUM TANKER FIRE ON N2 INCOMING FREEWAY</headline>
+      <description>
+        A liquid petroleoum tanker has caught fire on the N2 incoming freeway 1km
+        after the R300 interchange. Municipal fire fighting crews have been
+        dispatched. Traffic control officers are on the scene and have diverted
+        traffic onto alternate routes.
+      </description>
+    </info>
+  </alert>
+
+
+You can also create the various message elements seperately and then combine them later:
+
+ # Setting attributes at initialisation
+ alert = Alert.new( :sender   => 'cape_town_disaster_relief@capetown.municipal.za',
+                    :status   => Alert::STATUS_ACTUAL, 
+                    :msg_type => Alert::MSG_TYPE_ALERT,
+                    :scope    => Alert::SCOPE_PUBLIC )  
+ 
+ # Setting attributes after initialisation
+ info = Info.new 
+ info.event      = 'Liquid Petroleoum Tanker Fire'
+ info.language   = 'en-ZA'
+ info.categories = [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ]
+ info.urgency    = Info::URGENCY_IMMEDIATE
+ info.severity   = Info::SEVERITY_SEVERE
+ info.certainty  = Info::CERTAINTY_OBSERVED 
+
+
+ resource  = Resource.new( :resource_desc => 'Cape Town Municipal Traffic Management Guidelines',
+                           :uri           => 'http://capetown.municipal.za/traffic/management_guidelines.pdf',
+                           :mime_type     => 'application/pdf')
+
+ # Combining all elements
+ info.resources << resource
+ alert.infos << info
+
+=== Validating an alert
+
+The RCAP API aims to codify as many of the rules of the CAP XML format into validation rules that can be checked using the Assistance API (http://assistance.rubyforge.org). The following Info object has two attributes ('severity' and 'certainty') set to incorrect values.
+
+ info = Info.new( :event      => 'Liquid Petroleoum Tanker Fire',
+                  :language   => 'en-ZA',
+                  :categories => [ Info::CATEGORY_TRANSPORT, Info::CATEGORY_FIRE ],
+                  :urgency    => Info::URGENCY_IMMEDIATE,
+                  :severity   => nil,                   # Severity is not assigned
+                  :certainty  => 'Unknown Certainty' )  # Certainty is assigned in incorrect value
+ puts info.valid?
+ puts info.errors.full_messages
+
+Will produce the folling output:
+
+ false
+ severity is not present
+ certainty can only be assigned the following values: Observed, Likely, Possible, Unlikely, Unknown
+
+A full spec suite using RSpec (http://www.rspec.info) was used to test the validations and currently numbers over 140 tests.
+
+== Version
+
+0.1
+
+== Dependencies
+
+RCAP depends on the following gems
+
+* Assistance - http://assistance.rubyforge.org
+* UUIDTools - http://uuidtools.rubyforge.org
+ 
+== Authors
+
+Farrel Lifson - farrel.lifson@aimred.com
+
+== License
+
+RCAP is released under the BSD License.
+
+== Copyright
+
+2009 Aimred CC

data/lib/rcap.rb

@@ -0,0 +1,21 @@
+require 'date'
+require 'assistance'
+require 'uuidtools'
+require 'rexml/document'
+require 'rcap/utilities'
+require 'rcap/validations'
+require 'rcap/alert'
+require 'rcap/parameter'
+require 'rcap/event_code'
+require 'rcap/info'
+require 'rcap/resource'
+require 'rcap/point'
+require 'rcap/circle'
+require 'rcap/polygon'
+require 'rcap/geocode'
+require 'rcap/area'
+
+module RCAP
+	XMLNS = "urn:oasis:names:tc:emergency:cap:1.1"
+	VERSION = "0.1"
+end

data/lib/rcap/alert.rb

@@ -0,0 +1,186 @@
+module RCAP
+  # An Alert object is valid if 
+  # * it has an identifier
+  # * it has a sender
+  # * it has a sent time
+  # * it has a valid status value
+  # * it has a valid messge type value
+  # * it has a valid scope value
+  # * all Info objects contained in infos are valid
+	class Alert
+		include Validation
+
+		STATUS_ACTUAL   = "Actual"
+		STATUS_EXERCISE = "Exercise"
+		STATUS_SYSTEM   = "System"
+		STATUS_TEST     = "Test"
+		STATUS_DRAFT    = "Draft"
+		ALL_STATUSES = [ STATUS_ACTUAL, STATUS_EXERCISE, STATUS_SYSTEM, STATUS_TEST, STATUS_DRAFT ] #:nodoc:
+
+		MSG_TYPE_ALERT  = "Alert"
+		MSG_TYPE_UPDATE = "Update"
+		MSG_TYPE_CANCEL = "Cancel"
+		MSG_TYPE_ACK    = "Ack"
+		MSG_TYPE_ERROR  = "Error"
+		ALL_MSG_TYPES = [ MSG_TYPE_ALERT, MSG_TYPE_UPDATE, MSG_TYPE_CANCEL, MSG_TYPE_ACK, MSG_TYPE_ERROR ] #:nodoc:  
+
+		SCOPE_PUBLIC     = "Public"
+		SCOPE_RESTRICTED = "Restricted"
+		SCOPE_PRIVATE    = "Private"
+		ALL_SCOPES = [ SCOPE_PUBLIC, SCOPE_PRIVATE, SCOPE_RESTRICTED ] #:nodoc:
+
+    XML_ELEMENT_NAME         = 'alert'       # :nodoc:
+    IDENTIFIER_ELEMENT_NAME  = 'identifier'  # :nodoc:
+    SENDER_ELEMENT_NAME      = 'sender'      # :nodoc:
+    SENT_ELEMENT_NAME        = 'sent'        # :nodoc:
+    STATUS_ELEMENT_NAME      = 'status'      # :nodoc:
+    MSG_TYPE_ELEMENT_NAME    = 'msgType'     # :nodoc:
+    SOURCE_ELEMENT_NAME      = 'source'      # :nodoc:
+    SCOPE_ELEMENT_NAME       = 'scope'       # :nodoc:
+    RESTRICTION_ELEMENT_NAME = 'restriction' # :nodoc:
+    ADDRESSES_ELEMENT_NAME   = 'addresses'   # :nodoc:
+    CODE_ELEMENT_NAME        = 'code'        # :nodoc:
+    NOTE_ELEMENT_NAME        = 'note'        # :nodoc:
+    REFERENCES_ELEMENT_NAME  = 'references'  # :nodoc:
+    INCIDENTS_ELEMENT_NAME   = 'incidents'   # :nodoc:
+
+    XPATH             = 'cap:alert'                         # :nodoc: 
+    IDENTIFIER_XPATH  = "cap:#{ IDENTIFIER_ELEMENT_NAME }"  # :nodoc: 
+    SENDER_XPATH      = "cap:#{ SENDER_ELEMENT_NAME }"      # :nodoc: 
+    SENT_XPATH        = "cap:#{ SENT_ELEMENT_NAME }"        # :nodoc: 
+    STATUS_XPATH      = "cap:#{ STATUS_ELEMENT_NAME }"      # :nodoc: 
+    MSG_TYPE_XPATH    = "cap:#{ MSG_TYPE_ELEMENT_NAME }"    # :nodoc: 
+    SOURCE_XPATH      = "cap:#{ SOURCE_ELEMENT_NAME }"      # :nodoc: 
+    SCOPE_XPATH       = "cap:#{ SCOPE_ELEMENT_NAME }"       # :nodoc: 
+    RESTRICTION_XPATH = "cap:#{ RESTRICTION_ELEMENT_NAME }" # :nodoc: 
+    ADDRESSES_XPATH   = "cap:#{ ADDRESSES_ELEMENT_NAME }"   # :nodoc: 
+    CODE_XPATH        = "cap:#{ CODE_ELEMENT_NAME }"        # :nodoc: 
+    NOTE_XPATH        = "cap:#{ NOTE_ELEMENT_NAME }"        # :nodoc: 
+    REFERENCES_XPATH  = "cap:#{ REFERENCES_ELEMENT_NAME }"  # :nodoc: 
+    INCIDENTS_XPATH   = "cap:#{ INCIDENTS_ELEMENT_NAME }"   # :nodoc: 
+
+    # If not set a UUID will be set by default
+		attr_accessor( :identifier)
+    attr_accessor( :sender )
+    # Sent Time - If not set will value will be time of creation.
+    attr_accessor( :sent )
+    attr_accessor( :status )
+    # Message Type
+    attr_accessor( :msg_type )
+    attr_accessor( :scope )
+    attr_accessor( :source )
+    # Depends on scope being SCOPE_RESTRICTED. 
+    attr_accessor( :restriction )
+    attr_accessor( :code )
+    attr_accessor( :note )
+
+    # Collection of address strings. Depends on scope being SCOPE_PRIVATE.
+		attr_reader( :addresses )
+    # Collection of reference strings - see Alert#to_reference
+    attr_reader( :references) 
+    # Collection of incident strings
+    attr_reader( :incidents )
+    # Collection of Info objects
+    attr_reader( :infos )
+
+		validates_presence_of( :identifier, :sender, :sent, :status, :msg_type, :scope )
+
+    validates_inclusion_of( :status,   :in => ALL_STATUSES )
+    validates_inclusion_of( :msg_type, :in => ALL_MSG_TYPES )
+    validates_inclusion_of( :scope,    :in => ALL_SCOPES )
+
+    validates_format_of( :identifier, :with => ALLOWED_CHARACTERS )
+    validates_format_of( :sender ,    :with => ALLOWED_CHARACTERS )
+
+    validates_dependency_of( :addresses,   :on => :scope, :with_value => SCOPE_PRIVATE )
+    validates_dependency_of( :restriction, :on => :scope, :with_value => SCOPE_RESTRICTED )
+
+    validates_collection_of( :infos )
+
+		def initialize( attributes = {})
+			@identifier  = attributes[ :identifier ] || UUIDTools::UUID.random_create.to_s
+			@sender      = attributes[ :sender ]
+			@sent        = attributes[ :sent ] || DateTime.now
+			@status      = attributes[ :status ]
+			@msg_type    = attributes[ :msg_type ]
+			@scope       = attributes[ :scope ]
+			@source      = attributes[ :source ]
+			@restriction = attributes[ :restriction ]
+			@addresses   = Array( attributes[ :addresses ])
+			@references  = Array( attributes[ :references ])
+			@incidents   = Array( attributes[ :incidents ])
+			@infos       = Array( attributes[ :infos ])
+		end
+
+    def to_xml_element #:nodoc:
+      xml_element = REXML::Element.new( XML_ELEMENT_NAME )
+      xml_element.add_namespace( RCAP::XMLNS )
+      xml_element.add_element( IDENTIFIER_ELEMENT_NAME ).add_text( self.identifier ) 
+      xml_element.add_element( SENDER_ELEMENT_NAME ).add_text( self.sender ) 
+      xml_element.add_element( SENT_ELEMENT_NAME ).add_text( self.sent.to_s ) 
+      xml_element.add_element( STATUS_ELEMENT_NAME ).add_text( self.status ) 
+      xml_element.add_element( MSG_TYPE_ELEMENT_NAME ).add_text( self.msg_type ) 
+      xml_element.add_element( SOURCE_ELEMENT_NAME ).add_text( self.source ) if self.source
+      xml_element.add_element( SCOPE_ELEMENT_NAME ).add_text( self.scope ) 
+      xml_element.add_element( RESTRICTION_ELEMENT_NAME ).add_text( self.restriction ) if self.restriction
+      unless self.addresses.empty?
+        xml_element.add_element( ADDRESSES_ELEMENT_NAME ).add_text( self.addresses.to_s_for_cap )
+      end
+      xml_element.add_element( CODE_ELEMENT_NAME ).add_text( self.code ) if self.code
+      xml_element.add_element( NOTE_ELEMENT_NAME ).add_text( self.note ) if self.note
+      unless self.references.empty?
+        xml_element.add_element( REFERENCES_ELEMENT_NAME ).add_text( self.references.join( ' ' ))
+      end
+      unless self.incidents.empty?
+        xml_element.add_element( INCIDENTS_ELEMENT_NAME ).add_text( self.incidents.join( ' ' ))
+      end
+      self.infos.each do |info|
+        xml_element.add_element( info.to_xml_element )
+      end
+      xml_element
+    end
+
+    def to_xml_document #:nodoc:
+      xml_document = REXML::Document.new
+      xml_document.add( REXML::XMLDecl.new )
+      xml_document.add( self.to_xml_element )
+      xml_document
+    end
+
+    # Returns a string containing the XML representation of the alert.
+    def to_xml
+      self.to_xml_document.to_s
+    end
+
+    # Returns a string of the format 'sender,identifier,sent' suitable for usage as a reference in a CAP message.
+    def to_reference
+      "#{ self.sender },#{ self.identifier },#{ self.sent }"
+    end
+
+    def self.from_xml_element( alert_xml_element ) # :nodoc:
+      alert = RCAP::Alert.new( :identifier  => RCAP.xpath_text( alert_xml_element, RCAP::Alert::IDENTIFIER_XPATH ),
+                               :sender      => RCAP.xpath_text( alert_xml_element, SENDER_XPATH ),
+                               :sent        => (( sent = RCAP.xpath_first( alert_xml_element, SENT_XPATH )) ? DateTime.parse( sent.text ) : nil ),
+                               :status      => RCAP.xpath_text( alert_xml_element, STATUS_XPATH ),
+                               :msg_type    => RCAP.xpath_text( alert_xml_element, MSG_TYPE_XPATH ),
+                               :source      => RCAP.xpath_text( alert_xml_element, SOURCE_XPATH ),
+                               :scope       => RCAP.xpath_text( alert_xml_element, SCOPE_XPATH ),
+                               :restriction => RCAP.xpath_text( alert_xml_element, RESTRICTION_XPATH ),
+                               :addresses   => (( address = RCAP.xpath_text( alert_xml_element, ADDRESSES_XPATH )) ? address.unpack_cap_list : nil ),
+                               :code        => RCAP.xpath_text( alert_xml_element, CODE_XPATH ),
+                               :note        => RCAP.xpath_text( alert_xml_element, NOTE_XPATH ),
+                               :references  => (( references = RCAP.xpath_text( alert_xml_element, REFERENCES_XPATH )) ? references.split( ' ' ) : nil ),
+                               :incidents   => (( incidents = RCAP.xpath_text( alert_xml_element, INCIDENTS_XPATH )) ? incidents.split( ' ' ) : nil ),
+                               :infos       => RCAP.xpath_match( alert_xml_element, RCAP::Info::XPATH ).map{ |element| RCAP::Info.from_xml_element( element )})
+    end
+
+    def self.from_xml_document( xml_document ) # :nodoc:
+      self.from_xml_element( xml_document.root )
+    end
+
+    # Initialised an Alert object from the XML string.
+    def self.from_xml( xml_string )
+      self.from_xml_document( REXML::Document.new( xml_string ))
+    end
+	end
+end

data/lib/rcap/area.rb

@@ -0,0 +1,82 @@
+module RCAP
+	# An Area object is valid if
+	# * it has an area description
+	# * all Circle objects contained in circles are valid
+	# * all Geocode objects contained in geocodes are valid
+	# * all Polygon objects contained in polygons are valid
+	# * altitude has a value if ceiling is set
+  class Area
+    include Validation
+		
+		# Area Description - Textual description of area.
+		attr_accessor( :area_desc ) 
+		# Expressed in feet above sea level 
+    attr_accessor( :altitude )
+		# Expressed in feet above sea level.
+		attr_accessor( :ceiling )
+		# Collection of Circle objects
+    attr_reader( :circles )
+		# Collection of Geocode objects
+		attr_reader( :geocodes )
+		# Collection of Polygon objects
+		attr_reader( :polygons )
+
+    validates_presence_of( :area_desc )
+    validates_collection_of( :circles, :geocodes, :polygons )
+    validates_dependency_of( :ceiling, :on => :altitude )
+
+    XML_ELEMENT_NAME       = 'area'     # :nodoc: 
+    AREA_DESC_ELEMENT_NAME = 'areaDesc' # :nodoc: 
+    ALTITUDE_ELEMENT_NAME  = 'altitude' # :nodoc: 
+    CEILING_ELEMENT_NAME   = 'ceiling'  # :nodoc: 
+
+    XPATH           = "cap:#{ XML_ELEMENT_NAME }"       # :nodoc: 
+    AREA_DESC_XPATH = "cap:#{ AREA_DESC_ELEMENT_NAME }" # :nodoc: 
+    ALTITUDE_XPATH  = "cap:#{ ALTITUDE_ELEMENT_NAME }"  # :nodoc: 
+    CEILING_XPATH   = "cap:#{ CEILING_ELEMENT_NAME }"   # :nodoc: 
+
+    def initialize( attributes = {})
+      @area_desc = attributes[ :area_desc ]
+      @altitude  = attributes[ :altitude ]
+      @ceiling   = attributes[ :ceiling ]
+      @circles   = Array( attributes[ :circles ])
+      @geocodes  = Array( attributes[ :geocodes ])
+      @polygons  = Array( attributes[ :polygons ])
+    end
+
+    def to_xml_element # :nodoc:
+      xml_element = REXML::Element.new( XML_ELEMENT_NAME )
+      xml_element.add_element( AREA_DESC_ELEMENT_NAME ).add_text( @area_desc.to_s )
+      add_to_xml_element = lambda do |element, object|
+        element.add_element( object.to_xml_element )
+        element
+      end
+      @polygons.inject( xml_element, &add_to_xml_element )
+      @circles.inject( xml_element, &add_to_xml_element )
+      @geocodes.inject( xml_element, &add_to_xml_element )
+      xml_element.add_element( ALTITUDE_ELEMENT_NAME ).add_text( @altitude.to_s ) unless self.altitude.blank?
+      xml_element.add_element( CEILING_ELEMENT_NAME ).add_text( @ceiling.to_s ) unless self.altitude.blank?
+      xml_element
+    end
+
+    def to_xml # :nodoc:
+      self.to_xml_element.to_s
+    end
+
+		# Implements an equality operator for the Area object. Two Area objects are equal if all their attributes are equal.
+		def ==( other )  
+			comparison_attributes = lambda{ |area| [ area.area_desc, area.altitude, area.ceiling, area.circles, area.geocodes, area.polygons ]}
+			comparison_attributes.call( self ) == comparison_attributes.call( other )
+		end
+
+    def self.from_xml_element( area_xml_element ) # :nodoc:
+      area = RCAP::Area.new( :area_desc => RCAP.xpath_text( area_xml_element, AREA_DESC_XPATH ),
+														 :altitude  => (( alt = RCAP.xpath_text( area_xml_element, ALTITUDE_XPATH )) ? alt.to_f : nil ),
+														 :ceiling   => (( ceil = RCAP.xpath_text( area_xml_element, CEILING_XPATH )) ? ceil.to_f : nil ),
+														 :circles   => RCAP.xpath_match( area_xml_element, RCAP::Circle::XPATH ).map{ |circle_element| RCAP::Circle.from_xml_element( circle_element )},
+														 :geocodes  => RCAP.xpath_match( area_xml_element, RCAP::Geocode::XPATH ).map{ |geocode_element| RCAP::Geocode.from_xml_element( geocode_element )},
+														 :polygons  => RCAP.xpath_match( area_xml_element, RCAP::Polygon::XPATH ).map{ |polygon_element| RCAP::Polygon.from_xml_element( polygon_element )})
+			area
+    end
+  end
+end

data/lib/rcap/circle.rb

@@ -0,0 +1,62 @@
+module RCAP
+	# A Circle object is valid if
+	# * it has a point which is a valid Point object
+	# * it has a radius with a value greater than zero
+  class Circle
+    include Validation
+
+		# Instance of Point class
+    attr_accessor( :point )
+		# Expresed in kilometers 
+		attr_accessor( :radius )
+
+    validates_presence_of( :point, :radius )
+    validates_numericality_of( :radius , :greater_than => 0 )
+    validates_validity_of( :point )
+
+    XML_ELEMENT_NAME = 'circle' # :nodoc:
+
+    XPATH = 'cap:circle' # :nodoc:
+
+    def initialize( attributes = {} )
+      @point = attributes[ :point ]
+      @radius = attributes[ :radius ]
+    end
+
+    def to_s  # :nodoc:
+      "#{ self.point.to_s } #{ self.radius }"
+    end
+
+    def inspect # :nodoc:
+      "(#{ self.point.lattitude},#{ self.point.longitude } #{ self.radius })"
+    end
+
+    def to_xml_element # :nodoc:
+      xml_element = REXML::Element.new( XML_ELEMENT_NAME )
+      xml_element.add_text( self.to_s )
+      xml_element
+    end
+
+    def to_xml # :nodoc:
+      self.to_xml_element.to_s
+    end
+
+    def self.parse_circle_string( circle_string ) # :nodoc:
+      coordinates, radius = circle_string.split( ' ' )
+      lattitude, longitude = coordinates.split( ',' )
+      [ lattitude, longitude, radius ].map{ |e| e.to_f }
+    end
+
+    def self.from_xml_element( circle_xml_element ) # :nodoc:
+      lattitude, longitude, radius = self.parse_circle_string( circle_xml_element.text )
+      point = RCAP::Point.new( :lattitude => lattitude, :longitude => longitude )
+      circle = self.new( :point  => point,
+                         :radius => radius )
+    end
+
+		# Two circles are equivalent if their point and radius are equal.
+    def ==( other )
+      self.point == other.point && self.radius == other.radius
+    end
+  end
+end