rcap 1.3.1 → 2.0.0

data/lib/rcap/base/alert.rb

@@ -0,0 +1,446 @@
+module RCAP
+  module Base
+    class Alert
+      include Validation
+
+      STATUS_ACTUAL   = "Actual"
+      STATUS_EXERCISE = "Exercise"
+      STATUS_SYSTEM   = "System"
+      STATUS_TEST     = "Test"
+      # Valid values for status
+      VALID_STATUSES = [ STATUS_ACTUAL, STATUS_EXERCISE, STATUS_SYSTEM, STATUS_TEST ]
+
+      MSG_TYPE_ALERT  = "Alert"
+      MSG_TYPE_UPDATE = "Update"
+      MSG_TYPE_CANCEL = "Cancel"
+      MSG_TYPE_ACK    = "Ack"
+      MSG_TYPE_ERROR  = "Error"
+      # Valid values for msg_type
+      VALID_MSG_TYPES = [ MSG_TYPE_ALERT, MSG_TYPE_UPDATE, MSG_TYPE_CANCEL, MSG_TYPE_ACK, MSG_TYPE_ERROR ]
+
+      SCOPE_PUBLIC     = "Public"
+      SCOPE_RESTRICTED = "Restricted"
+      SCOPE_PRIVATE    = "Private"
+      # Valid values for scope
+      VALID_SCOPES = [ SCOPE_PUBLIC, SCOPE_PRIVATE, SCOPE_RESTRICTED ]
+
+      # @return [String] If not set a UUID will be set by default on object initialisation
+      attr_accessor( :identifier)
+      # @return [String]
+      attr_accessor( :sender )
+      # @return [DateTime] If not set will be time of creation.
+      attr_accessor( :sent )
+      # @return [String] Can only be one of {VALID_STATUSES}
+      attr_accessor( :status )
+      # @return [String] Can only be one of {VALID_MSG_TYPES}
+      attr_accessor( :msg_type )
+      # @return [String] Can only be one of {VALID_SCOPES}
+      attr_accessor( :scope )
+      # @return [String]
+      attr_accessor( :source )
+      # @return [String ] Required if scope is {SCOPE_RESTRICTED}
+      attr_accessor( :restriction )
+      # @return [String]
+      attr_accessor( :note )
+
+      # @return [Array<String>] Collection of address strings. Depends on scope being {SCOPE_PRIVATE}
+      attr_reader( :addresses )
+      # @return [Array<String>]
+      attr_reader( :codes )
+      # @return [Array<String>] Collection of references to previous alerts
+      # @see #to_reference
+      attr_reader( :references)
+      # @return [Array<String>] Collection of incident strings
+      attr_reader( :incidents )
+      # @return [Array<Info>]
+      attr_reader( :infos )
+
+      validates_presence_of( :identifier, :sender, :sent, :status, :msg_type, :scope )
+
+      validates_inclusion_of( :status,   :in => VALID_STATUSES )
+      validates_inclusion_of( :msg_type, :in => VALID_MSG_TYPES )
+      validates_inclusion_of( :scope,    :in => VALID_SCOPES )
+
+      validates_format_of( :identifier, :with => ALLOWED_CHARACTERS )
+      validates_format_of( :sender ,    :with => ALLOWED_CHARACTERS )
+
+      validates_conditional_presence_of( :addresses,   :when => :scope, :is => SCOPE_PRIVATE )
+      validates_conditional_presence_of( :restriction, :when => :scope, :is => SCOPE_RESTRICTED )
+
+      validates_collection_of( :infos )
+
+      # Initialises a new Alert object. Yields the initialised alert to a block.
+      #
+      # @example
+      #   alert = Alert.new do |alert|
+      #             alert.sender = alerts@example.org
+      #             alert.status = Alert::STATUS_ACTUAL
+      #             alert.msg_type = Alert::MSG_TYPE_ALERT
+      #             alert.scope = Alert::SCOPE_PUBLIC
+      #           end
+      #
+      # @yieldparam alert [Alert] The newly initialised Alert.
+      def initialize
+        @identifier  = RCAP.generate_identifier
+        @addresses   = []
+        @codes       = []
+        @references  = []
+        @incidents   = []
+        @infos       = []
+        yield( self ) if block_given?
+      end
+
+      # Creates a new {Info} object and adds it to the {#infos} array.
+      #
+      # @see Info#initialize
+      # @yield [Info] The newly initialised Info object.
+      # @return [Info] The initialised Info object after being yielded to the block
+      def add_info
+        self.info_class.new.tap do |info|
+          yield( info ) if block_given?
+          @infos << info
+        end
+      end
+
+      XML_ELEMENT_NAME         = 'alert'
+      IDENTIFIER_ELEMENT_NAME  = 'identifier'
+      SENDER_ELEMENT_NAME      = 'sender'
+      SENT_ELEMENT_NAME        = 'sent'
+      STATUS_ELEMENT_NAME      = 'status'
+      MSG_TYPE_ELEMENT_NAME    = 'msgType'
+      SOURCE_ELEMENT_NAME      = 'source'
+      SCOPE_ELEMENT_NAME       = 'scope'
+      RESTRICTION_ELEMENT_NAME = 'restriction'
+      ADDRESSES_ELEMENT_NAME   = 'addresses'
+      CODE_ELEMENT_NAME        = 'code'
+      NOTE_ELEMENT_NAME        = 'note'
+      REFERENCES_ELEMENT_NAME  = 'references'
+      INCIDENTS_ELEMENT_NAME   = 'incidents'
+
+      # @return [REXML::Element]
+      def to_xml_element
+        xml_element = REXML::Element.new( XML_ELEMENT_NAME )
+        xml_element.add_namespace( self.class::XMLNS )
+        xml_element.add_element( IDENTIFIER_ELEMENT_NAME ).add_text( @identifier )   if @identifier
+        xml_element.add_element( SENDER_ELEMENT_NAME ).add_text( @sender )           if @sender
+        xml_element.add_element( SENT_ELEMENT_NAME ).add_text( @sent.to_s_for_cap )  if @sent
+        xml_element.add_element( STATUS_ELEMENT_NAME ).add_text( @status )           if @status
+        xml_element.add_element( MSG_TYPE_ELEMENT_NAME ).add_text( @msg_type )       if @msg_type
+        xml_element.add_element( SOURCE_ELEMENT_NAME ).add_text( @source )           if @source
+        xml_element.add_element( SCOPE_ELEMENT_NAME ).add_text( @scope )             if @scope
+        xml_element.add_element( RESTRICTION_ELEMENT_NAME ).add_text( @restriction ) if @restriction
+        if @addresses.any?
+          xml_element.add_element( ADDRESSES_ELEMENT_NAME ).add_text( @addresses.to_s_for_cap )
+        end
+        @codes.each do |code|
+          xml_element.add_element( CODE_ELEMENT_NAME ).add_text( code )
+        end
+        xml_element.add_element( NOTE_ELEMENT_NAME ).add_text( @note ) if @note
+        if @references.any?
+          xml_element.add_element( REFERENCES_ELEMENT_NAME ).add_text( @references.join( ' ' ))
+        end
+        if @incidents.any?
+          xml_element.add_element( INCIDENTS_ELEMENT_NAME ).add_text( @incidents.join( ' ' ))
+        end
+        @infos.each do |info|
+          xml_element.add_element( info.to_xml_element )
+        end
+        xml_element
+      end
+
+      # @return [REXML::Document]
+      def to_xml_document
+        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.
+      #
+      # @param [true,false] pretty_print Pretty print output
+      # @return [String]
+      def to_xml( pretty_print = false )
+        if pretty_print
+          xml_document = ""
+          RCAP::XML_PRETTY_PRINTER.write( self.to_xml_document, xml_document )
+          xml_document
+        else
+          self.to_xml_document.to_s
+        end
+      end
+
+      # Returns a string representation of the alert suitable for usage as a reference in a CAP message of the form
+      #  sender,identifier,sent
+      #
+      # @return [String]
+      def to_reference
+        "#{ @sender },#{ @identifier },#{ @sent }"
+      end
+
+      # @return [String]
+      def inspect
+        alert_inspect = [ "CAP Version:  #{ self.class::CAP_VERSION }",
+                          "Identifier:   #{ @identifier }",
+                          "Sender:       #{ @sender }",
+                          "Sent:         #{ @sent }",
+                          "Status:       #{ @status }",
+                          "Message Type: #{ @msg_type }",
+                          "Source:       #{ @source }",
+                          "Scope:        #{ @scope }",
+                          "Restriction:  #{ @restriction }",
+                          "Addresses:    #{ @addresses.to_s_for_cap }",
+                          "Codes:",
+                          @codes.map{ |code| "  " + code }.join("\n")+"",
+                          "Note:         #{ @note }",
+                          "References:   #{ @references.join( ' ' )}",
+                          "Incidents:    #{ @incidents.join( ' ')}",
+                          "Information:",
+                          @infos.map{ |info| "  " + info.to_s }.join( "\n" )].join( "\n" )
+        RCAP.format_lines_for_inspect( 'ALERT', alert_inspect )
+      end
+
+      # Returns a string representation of the alert of the form
+      #  sender/identifier/sent
+      # See {#to_reference} for another string representation suitable as a CAP reference.
+      #
+      # @return [String]
+      def to_s
+        "#{ @sender }/#{ @identifier }/#{ @sent }"
+      end
+
+      XPATH             = 'cap:alert'
+      IDENTIFIER_XPATH  = "cap:#{ IDENTIFIER_ELEMENT_NAME }"
+      SENDER_XPATH      = "cap:#{ SENDER_ELEMENT_NAME }"
+      SENT_XPATH        = "cap:#{ SENT_ELEMENT_NAME }"
+      STATUS_XPATH      = "cap:#{ STATUS_ELEMENT_NAME }"
+      MSG_TYPE_XPATH    = "cap:#{ MSG_TYPE_ELEMENT_NAME }"
+      SOURCE_XPATH      = "cap:#{ SOURCE_ELEMENT_NAME }"
+      SCOPE_XPATH       = "cap:#{ SCOPE_ELEMENT_NAME }"
+      RESTRICTION_XPATH = "cap:#{ RESTRICTION_ELEMENT_NAME }"
+      ADDRESSES_XPATH   = "cap:#{ ADDRESSES_ELEMENT_NAME }"
+      CODE_XPATH        = "cap:#{ CODE_ELEMENT_NAME }"
+      NOTE_XPATH        = "cap:#{ NOTE_ELEMENT_NAME }"
+      REFERENCES_XPATH  = "cap:#{ REFERENCES_ELEMENT_NAME }"
+      INCIDENTS_XPATH   = "cap:#{ INCIDENTS_ELEMENT_NAME }"
+
+      # @param [REXML::Element] alert_xml_element
+      # @return [RCAP::CAP_1_0::Alert]
+      def self.from_xml_element( alert_xml_element )
+        self.new do |alert|
+          alert.identifier  = RCAP.xpath_text( alert_xml_element, IDENTIFIER_XPATH, alert.xmlns )
+          alert.sender      = RCAP.xpath_text( alert_xml_element, SENDER_XPATH, alert.xmlns )
+          alert.sent        = (( sent = RCAP.xpath_first( alert_xml_element, SENT_XPATH, alert.xmlns )) ? DateTime.parse( sent.text ) : nil )
+          alert.status      = RCAP.xpath_text( alert_xml_element, STATUS_XPATH, alert.xmlns )
+          alert.msg_type    = RCAP.xpath_text( alert_xml_element, MSG_TYPE_XPATH, alert.xmlns )
+          alert.source      = RCAP.xpath_text( alert_xml_element, SOURCE_XPATH, alert.xmlns )
+          alert.scope       = RCAP.xpath_text( alert_xml_element, SCOPE_XPATH, alert.xmlns )
+          alert.restriction = RCAP.xpath_text( alert_xml_element, RESTRICTION_XPATH, alert.xmlns )
+
+          (( address = RCAP.xpath_text( alert_xml_element, ADDRESSES_XPATH, alert.xmlns )) ? address.unpack_cap_list : [] ).each do |address|
+            alert.addresses << address
+          end
+          RCAP.xpath_match( alert_xml_element, CODE_XPATH, alert.xmlns ).each do |element|
+            alert.codes << element.text
+          end
+          alert.note        = RCAP.xpath_text( alert_xml_element, NOTE_XPATH, alert.xmlns )
+          (( references = RCAP.xpath_text( alert_xml_element, REFERENCES_XPATH, alert.xmlns )) ? references.split( ' ' ) : []).each do |reference|
+            alert.references << reference
+          end
+
+          (( incidents = RCAP.xpath_text( alert_xml_element, INCIDENTS_XPATH, alert.xmlns )) ? incidents.split( ' ' ) : []).each do |incident|
+            alert.incidents << incident
+          end
+
+          RCAP.xpath_match( alert_xml_element, Info::XPATH, alert.xmlns ).each do |element|
+            alert.infos << alert.info_class.from_xml_element( element )
+          end
+        end
+      end
+
+      # @param [REXML::Document] xml_document
+      # @return [Alert]
+      def self.from_xml_document( xml_document )
+        self.from_xml_element( xml_document.root )
+      end
+
+      # Initialise an Alert object from an XML string. Any object that is a subclass of IO (e.g. File) can be passed in.
+      #
+      # @param [String] xml
+      # @return [Alert]
+      def self.from_xml( xml )
+        self.from_xml_document( REXML::Document.new( xml ))
+      end
+
+      CAP_VERSION_YAML = "CAP Version"
+      IDENTIFIER_YAML  = "Identifier"
+      SENDER_YAML      = "Sender"
+      SENT_YAML        = "Sent"
+      STATUS_YAML      = "Status"
+      MSG_TYPE_YAML    = "Message Type"
+      SOURCE_YAML      = "Source"
+      SCOPE_YAML       = "Scope"
+      RESTRICTION_YAML = "Restriction"
+      ADDRESSES_YAML   = "Addresses"
+      CODES_YAML       = "Codes"
+      NOTE_YAML        = "Note"
+      REFERENCES_YAML  = "References"
+      INCIDENTS_YAML   = "Incidents"
+      INFOS_YAML       = "Information"
+
+      # Returns a string containing the YAML representation of the alert.
+      #
+      # @return [String]
+      def to_yaml( options = {} )
+        RCAP.attribute_values_to_hash( [ CAP_VERSION_YAML, self.class::CAP_VERSION ],
+                                       [ IDENTIFIER_YAML,  @identifier ],
+                                       [ SENDER_YAML,      @sender ],
+                                       [ SENT_YAML,        @sent ],
+                                       [ STATUS_YAML,      @status ],
+                                       [ MSG_TYPE_YAML,    @msg_type ],
+                                       [ SOURCE_YAML,      @source ],
+                                       [ SCOPE_YAML,       @scope ],
+                                       [ RESTRICTION_YAML, @restriction ],
+                                       [ ADDRESSES_YAML,   @addresses ],
+                                       [ CODES_YAML,       @codes ],
+                                       [ NOTE_YAML,        @note ],
+                                       [ REFERENCES_YAML,  @references ],
+                                       [ INCIDENTS_YAML,   @incidents ],
+                                       [ INFOS_YAML,       @infos ]).to_yaml( options )
+      end
+
+      # Initialise an Alert object from a YAML string. Any object that is a subclass of IO (e.g. File) can be passed in.
+      #
+      # @param [String] yaml
+      # @return [Alert]
+      def self.from_yaml( yaml )
+        self.from_yaml_data( YAML.load( yaml ))
+      end
+
+      # Initialise an Alert object from a hash reutrned from YAML.load.
+      #
+      # @param [hash] alert_yaml_data
+      # @return [Alert]
+      def self.from_yaml_data( alert_yaml_data )
+        self.new do |alert|
+          alert.identifier  = alert_yaml_data[ IDENTIFIER_YAML ]
+          alert.sender      = alert_yaml_data[ SENDER_YAML ]
+          alert.sent        = ( sent = alert_yaml_data[ SENT_YAML ]).blank? ? nil : DateTime.parse( sent.to_s )
+          alert.status      = alert_yaml_data[ STATUS_YAML ]
+          alert.msg_type    = alert_yaml_data[ MSG_TYPE_YAML ]
+          alert.source      = alert_yaml_data[ SOURCE_YAML ]
+          alert.scope       = alert_yaml_data[ SCOPE_YAML ]
+          alert.restriction = alert_yaml_data[ RESTRICTION_YAML ]
+          Array( alert_yaml_data[ ADDRESSES_YAML ]).each do |address|
+            alert.addresses << address
+          end
+          Array( alert_yaml_data[ CODES_YAML ]).each do |code|
+            alert.codes << code
+          end
+          alert.note        = alert_yaml_data[ NOTE_YAML ]
+          Array( alert_yaml_data[ REFERENCES_YAML ]).each do |reference|
+            alert.references << reference
+          end
+          Array( alert_yaml_data[ INCIDENTS_YAML ]).each do |incident|
+            alert.incidents << incident
+          end
+          Array( alert_yaml_data[ INFOS_YAML ]).each do |info_yaml_data|
+            alert.infos <<  alert.info_class.from_yaml_data( info_yaml_data )
+          end
+        end
+      end
+
+      CAP_VERSION_KEY = 'cap_version'
+      IDENTIFIER_KEY  = 'identifier'
+      SENDER_KEY      = 'sender'
+      SENT_KEY        = 'sent'
+      STATUS_KEY      = 'status'
+      MSG_TYPE_KEY    = 'msg_type'
+      SOURCE_KEY      = 'source'
+      SCOPE_KEY       = 'scope'
+      RESTRICTION_KEY = 'restriction'
+      ADDRESSES_KEY   = 'addresses'
+      CODES_KEY       = 'codes'
+      NOTE_KEY        = 'note'
+      REFERENCES_KEY  = 'references'
+      INCIDENTS_KEY   = 'incidents'
+      INFOS_KEY       = 'infos'
+
+      # Returns a Hash representation of an Alert object
+      #
+      # @return [Hash]
+      def to_h
+        RCAP.attribute_values_to_hash( [ CAP_VERSION_KEY, self.class::CAP_VERSION ],
+                                       [ IDENTIFIER_KEY,  @identifier ],
+                                       [ SENDER_KEY,      @sender ],
+                                       [ SENT_KEY,        RCAP.to_s_for_cap( @sent )],
+                                       [ STATUS_KEY,      @status ],
+                                       [ MSG_TYPE_KEY,    @msg_type ],
+                                       [ SOURCE_KEY,      @source ],
+                                       [ SCOPE_KEY,       @scope ],
+                                       [ RESTRICTION_KEY, @restriction ],
+                                       [ ADDRESSES_KEY,   @addresses ],
+                                       [ CODES_KEY,       @codes ],
+                                       [ NOTE_KEY,        @note ],
+                                       [ REFERENCES_KEY,  @references ],
+                                       [ INCIDENTS_KEY,   @incidents ],
+                                       [ INFOS_KEY,       @infos.map{ |info| info.to_h  }])
+      end
+
+      # Initialises an Alert object from a Hash produced by Alert#to_h
+      #
+      # @param [Hash] alert_hash
+      # @return [RCAP::CAP_1_0::Alert]
+      def self.from_h( alert_hash )
+        self.new do |alert|
+          alert.identifier  = alert_hash[ IDENTIFIER_KEY ]
+          alert.sender      = alert_hash[ SENDER_KEY ]
+          alert.sent        = RCAP.parse_datetime( alert_hash[ SENT_KEY ])
+          alert.status      = alert_hash[ STATUS_KEY ]
+          alert.msg_type    = alert_hash[ MSG_TYPE_KEY ]
+          alert.source      = alert_hash[ SOURCE_KEY ]
+          alert.scope       = alert_hash[ SCOPE_KEY ]
+          alert.restriction = alert_hash[ RESTRICTION_KEY ]
+          Array( alert_hash[ ADDRESSES_KEY ]).each do |address|
+            alert.addresses << address
+          end
+          Array( alert_hash[ CODES_KEY ]).each do |code|
+            alert.codes << code
+          end
+          alert.note = alert_hash[ NOTE_KEY ]
+          Array( alert_hash[ REFERENCES_KEY ]).each do |reference|
+            alert.references << reference
+          end
+
+          Array( alert_hash[ INCIDENTS_KEY ]).each do |incident|
+            alert.incidents << incident
+          end
+
+          Array( alert_hash[ INFOS_KEY ]).each do |info_hash|
+            alert.infos << alert.info_class.from_h( info_hash )
+          end
+        end
+      end
+
+      # Returns a JSON string representation of an Alert object
+      #
+      # @param [true,false] pretty_print
+      # @return [String]
+      def to_json( pretty_print = false )
+        if pretty_print
+          JSON.pretty_generate( self.to_h )
+        else
+          self.to_h.to_json
+        end
+      end
+
+      # Initialises an Alert object from a JSON string produced by Alert#to_json
+      #
+      # @param [String] json_string
+      # @return [Alert]
+      def self.from_json( json_string )
+        self.from_h( JSON.parse( json_string ))
+      end
+    end
+  end
+end

data/lib/rcap/base/area.rb

@@ -0,0 +1,228 @@
+module RCAP
+  module Base
+    class Area
+      include Validation
+
+      # @return [String] Textual description of area.
+      attr_accessor( :area_desc )
+      # @return [Numeric] Expressed in feet above sea level
+      attr_accessor( :altitude )
+      # @return [Numeric] Expressed in feet above sea level.
+      attr_accessor( :ceiling )
+      # @return [Array<Circle>]
+      attr_reader( :circles )
+      # @return [Array<Geocode>]
+      attr_reader( :geocodes )
+      # @return [Array<Polygon>]
+      attr_reader( :polygons )
+
+      validates_presence_of( :area_desc )
+      validates_collection_of( :circles, :geocodes, :polygons, allow_empty: true )
+      validates_dependency_of( :ceiling, on: :altitude )
+
+      XML_ELEMENT_NAME       = 'area'
+      AREA_DESC_ELEMENT_NAME = 'areaDesc'
+      ALTITUDE_ELEMENT_NAME  = 'altitude'
+      CEILING_ELEMENT_NAME   = 'ceiling'
+
+      XPATH           = "cap:#{ XML_ELEMENT_NAME }"
+      AREA_DESC_XPATH = "cap:#{ AREA_DESC_ELEMENT_NAME }"
+      ALTITUDE_XPATH  = "cap:#{ ALTITUDE_ELEMENT_NAME }"
+      CEILING_XPATH   = "cap:#{ CEILING_ELEMENT_NAME }"
+
+      # @example
+      #   Area.new do |area|
+      #     area.area_desc = 'Cape Town CVD'
+      #   end
+      def initialize
+        @area_desc = nil
+        @altitude  = nil
+        @ceiling   = nil
+
+        @circles  = []
+        @geocodes = []
+        @polygons = []
+        yield( self ) if block_given?
+      end
+
+      # Creates a new {Polygon} object and adds it to the {#polygons} array.
+      #
+      # @return [Polygon]
+      def add_polygon
+        self.polygon_class.new.tap do |polygon|
+          yield( polygon ) if block_given?
+          @polygons << polygon
+        end
+      end
+
+      # Creates a new {Circle} object and adds it to the {#circles} array.
+      #
+      # @return [Circle]
+      def add_circle
+        self.circle_class.new.tap do |circle|
+          yield( circle ) if block_given?
+          @circles << circle
+        end
+      end
+
+      # Creates a new {Geocode} object and adds it to the {#geocodes} array.
+      #
+      # @return [Geocode]
+      def add_geocode
+        self.geocode_class.new do |geocode|
+          yield( geocode ) if block_given?
+          @geocodes << geocode
+        end
+      end
+
+      def self.from_xml_element( area_xml_element )
+        self.new do |area|
+          area.area_desc = RCAP.xpath_text( area_xml_element, AREA_DESC_XPATH, area.xmlns )
+          area.altitude  = (( alt = RCAP.xpath_text( area_xml_element, ALTITUDE_XPATH, area.xmlns )) ? alt.to_f : nil )
+          area.ceiling   = (( ceil = RCAP.xpath_text( area_xml_element, CEILING_XPATH, area.xmlns )) ? ceil.to_f : nil )
+
+          RCAP.xpath_match( area_xml_element, area.circle_class::XPATH, area.xmlns ).each do |circle_element|
+            area.circles << area.circle_class.from_xml_element( circle_element )
+          end
+
+          RCAP.xpath_match( area_xml_element, area.geocode_class::XPATH, area.xmlns ).each do |geocode_element|
+            area.geocodes  << area.geocode_class.from_xml_element( geocode_element )
+          end
+
+          RCAP.xpath_match( area_xml_element, area.polygon_class::XPATH, area.xmlns ).each do |polygon_element|
+            area.polygons  << area.polygon_class.from_xml_element( polygon_element )
+          end
+        end
+      end
+
+      # @return [REXML::Element]
+      def to_xml_element
+        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 @altitude.blank?
+        xml_element.add_element( CEILING_ELEMENT_NAME ).add_text( @ceiling.to_s )   unless @altitude.blank?
+        xml_element
+      end
+
+      # @return [String] XML representation of the Area
+      def to_xml
+        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.
+      #
+      # @param [Area] other Area object to compare
+      # @return [true,false]
+      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
+
+      # @return [String]
+      def inspect
+        area_inspect = "Area Description: #{ @area_desc }\n"+
+                       "Polygons:\n"+
+                       @polygons.map{ |polygon| "  " + polygon.inspect }.join("\n" )+"\n"+
+                       "Circles:          #{ @circles.inspect }\n"+
+                       "Geocodes:         #{ @geocodes.inspect }\n"
+        RCAP.format_lines_for_inspect( 'AREA', area_inspect )
+      end
+
+      # Returns the area description
+      #
+      # @return [String]
+      def to_s
+        @area_desc
+      end
+
+
+      AREA_DESC_YAML = 'Area Description'
+      ALTITUDE_YAML  = 'Altitude'
+      CEILING_YAML   = 'Ceiling'
+      CIRCLES_YAML   = 'Circles'
+      GEOCODES_YAML  = 'Geocodes'
+      POLYGONS_YAML  = 'Polygons'
+
+      # @return [String] YAML representation of object
+      def to_yaml( options = {} )
+        RCAP.attribute_values_to_hash( [ AREA_DESC_YAML, @area_desc ],
+                                       [ ALTITUDE_YAML,  @altitude ],
+                                       [ CEILING_YAML,   @ceiling ],
+                                       [ CIRCLES_YAML,   @circles.map{ |circle| circle.to_a }],
+                                       [ GEOCODES_YAML,  @geocodes.inject({}){|h,geocode| h.merge( geocode.name => geocode.value )}],
+                                       [ POLYGONS_YAML,  @polygons ]).to_yaml( options )
+      end
+
+      # @param [Hash] area_yaml_data
+      # @return [Area]
+      def self.from_yaml_data( area_yaml_data )
+        self.new do |area|
+          area.area_desc = area_yaml_data[ AREA_DESC_YAML ]
+          area.altitude  = area_yaml_data[ ALTITUDE_YAML ]
+          area.ceiling   = area_yaml_data[ CEILING_YAML ]
+
+          Array( area_yaml_data[ CIRCLES_YAML ]).each do |circle_yaml_data|
+            area.circles << area.circle_class.from_yaml_data( circle_yaml_data )
+          end
+
+          Array( area_yaml_data[ GEOCODES_YAML ]).each do |name, value|
+            area.add_geocode do |geocode|
+              geocode.name = name
+              geocode.value = value
+            end
+          end
+
+          Array( area_yaml_data[ POLYGONS_YAML ]).each do |polyon_yaml_data|
+            area.polygons << area.polygon_class.from_yaml_data( polyon_yaml_data )
+          end
+        end
+      end
+
+      AREA_DESC_KEY = 'area_desc'
+      ALTITUDE_KEY  = 'altitude'
+      CEILING_KEY   = 'ceiling'
+      CIRCLES_KEY   = 'circles'
+      GEOCODES_KEY  = 'geocodes'
+      POLYGONS_KEY  = 'polygons'
+
+      # @param [Hash] area_hash
+      # @return [Area]
+      def self.from_h( area_hash )
+        self.new do |area|
+          area.area_desc = area_hash[ AREA_DESC_KEY ]
+          area.altitude  = area_hash[ ALTITUDE_KEY ]
+          area.ceiling   = area_hash[ CEILING_KEY ]
+
+          Array( area_hash[ CIRCLES_KEY ]).each do |circle_array|
+            area.circles << area.circle_class.from_a( circle_array )
+          end
+
+          Array( area_hash[ GEOCODES_KEY ]).each do |geocode_hash|
+            area.geocodes << area.geocode_class.from_h( geocode_hash )
+          end
+
+          Array( area_hash[ POLYGONS_KEY ]).each do |polygon_hash|
+            area.polygons << area.polygon_class.from_h( polygon_hash )
+          end
+        end
+      end
+
+      # @return [Hash]
+      def to_h
+        RCAP.attribute_values_to_hash( [ AREA_DESC_KEY, @area_desc ],
+                                       [ ALTITUDE_KEY,  @altitude ],
+                                       [ CEILING_KEY,   @ceiling ],
+                                       [ CIRCLES_KEY,   @circles.map{ |circle| circle.to_a }],
+                                       [ GEOCODES_KEY,  @geocodes.map{ |geocode| geocode.to_h }],
+                                       [ POLYGONS_KEY,  @polygons.map{ |polygon| polygon.to_h }])
+      end
+    end
+  end
+end