rcap 1.3.0 → 1.3.1

data/lib/rcap/cap_1_2/parameter.rb

@@ -8,57 +8,77 @@ module RCAP
 
       validates_presence_of( :name, :value )
 
-      attr_accessor( :name, :value )
+      # @return [String]
+      attr_accessor( :name )
+      # @return [String]
+      attr_accessor( :value )
 
-      XML_ELEMENT_NAME   = "parameter" # :nodoc:
-      NAME_ELEMENT_NAME  = "valueName" # :nodoc:
-      VALUE_ELEMENT_NAME = "value"     # :nodoc:
+      XML_ELEMENT_NAME   = "parameter" 
+      NAME_ELEMENT_NAME  = "valueName" 
+      VALUE_ELEMENT_NAME = "value"     
 
-      XPATH       = "cap:#{ XML_ELEMENT_NAME }"     # :nodoc:
-      NAME_XPATH  = "cap:#{ NAME_ELEMENT_NAME }"    # :nodoc:
-      VALUE_XPATH = "cap:#{ VALUE_ELEMENT_NAME }"   # :nodoc:
+      XPATH       = "cap:#{ XML_ELEMENT_NAME }"     
+      NAME_XPATH  = "cap:#{ NAME_ELEMENT_NAME }"    
+      VALUE_XPATH = "cap:#{ VALUE_ELEMENT_NAME }"   
 
+      # @param [Hash] attributes
+      # @option attributes [Symbol] :name Parameter name
+      # @option attributes [Symbol] :value Parameter value
       def initialize( attributes = {} )
         @name = attributes[ :name ]
         @value = attributes[ :value ]
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( self.class::XML_ELEMENT_NAME )
-        xml_element.add_element( NAME_ELEMENT_NAME ).add_text( self.name )
-        xml_element.add_element( VALUE_ELEMENT_NAME ).add_text( self.value )
+        xml_element.add_element( self.class::NAME_ELEMENT_NAME ).add_text( @name )
+        xml_element.add_element( self.class::VALUE_ELEMENT_NAME ).add_text( @value )
         xml_element
       end
 
-      def to_xml # :nodoc:
+      # @return [String]
+      def to_xml 
         self.to_xml_element.to_s
       end
 
-      def inspect # :nodoc:
-        "#{ self.name }: #{ self.value }"
+      # @return [String]
+      def inspect 
+        "#{ @name }: #{ @value }"
       end
 
       # Returns a string representation of the parameter of the form
       #  name: value
+      #
+      # @return [String]
       def to_s
         self.inspect
       end
 
+      # @param [REXML::Element] parameter_xml_element
+      # @return [Parameter] 
       def self.from_xml_element( parameter_xml_element ) # :nodoc:
-        self.new( :name  => RCAP.xpath_text( parameter_xml_element, NAME_XPATH, Alert::XMLNS ),
-                 :value => RCAP.xpath_text( parameter_xml_element, VALUE_XPATH, Alert::XMLNS ))
+        self.new( :name  => RCAP.xpath_text( parameter_xml_element, self::NAME_XPATH, Alert::XMLNS ),
+                  :value => RCAP.xpath_text( parameter_xml_element, self::VALUE_XPATH, Alert::XMLNS ))
       end
 
       # Two parameters are equivalent if they have the same name and value.
+      #
+      # @param [Parameter] other
+      # @return [true, false]
       def ==( other )
-        [ self.name, self.value ] == [ other.name, other.value ]
+        [ @name, @value ] == [ other.name, other.value ]
       end
 
-      def to_h # :nodoc:
-        RCAP.attribute_values_to_hash( [ self.name, self.value ])
+      # @return [Hash]
+      def to_h 
+        RCAP.attribute_values_to_hash(
+          [ @name, @value ])
       end
 
-      def self.from_h( hash ) # :nodoc:
+      # @param [Hash] hash
+      # @return [Parameter]
+      def self.from_h( hash ) 
         key = hash.keys.first
         self.new( :name => key, :value => hash[ key ])
       end

data/lib/rcap/cap_1_2/point.rb

@@ -11,13 +11,18 @@ module RCAP
       MAX_LATTITUDE = 90
       MIN_LATTITUDE= -90
 
+      # @return [Numeric]
       attr_accessor( :lattitude )
+      # @return [Numeric]
       attr_accessor( :longitude )
 
       validates_numericality_of( :lattitude, :longitude )
       validates_inclusion_of( :lattitude, :in => MIN_LATTITUDE..MAX_LATTITUDE )
       validates_inclusion_of( :longitude, :in => MIN_LONGITUDE..MAX_LONGITUDE)
 
+      # @param [Hash] attributes
+      # @option attributes [Numeric] :lattitude
+      # @option attributes [Numeric] :longitude
       def initialize( attributes = {} )
         @lattitude = attributes[ :lattitude ]
         @longitude = attributes[ :longitude ]
@@ -25,29 +30,38 @@ module RCAP
 
       # Returns a string representation of the point of the form
       #  lattitude,longitude
+      #
+      # @return [String]
       def to_s
-        "#{ self.lattitude },#{ self.longitude }"
+        "#{ @lattitude },#{ @longitude }"
       end
 
-      def inspect # :nodoc:
+      # @return [String]
+      def inspect 
         '('+self.to_s+')'
       end
 
       # Two points are equivalent if they have the same lattitude and longitude
+      #
+      # @param [Point] other
+      # @return [true, false]
       def ==( other )
-        [ self.lattitude, self.longitude ] == [ other.lattitude, other.longitude ]
+        [ @lattitude, @longitude ] == [ other.lattitude, other.longitude ]
       end
 
-      LATTITUDE_KEY = 'lattitude'  # :nodoc:
-      LONGITUDE_KEY = 'longitude'  # :nodoc:
+      LATTITUDE_KEY = 'lattitude'  
+      LONGITUDE_KEY = 'longitude'  
 
-      def to_h # :nodoc:
+      # @return [Hash]
+      def to_h 
         RCAP.attribute_values_to_hash(
-          [ LATTITUDE_KEY, self.lattitude ],
-          [ LONGITUDE_KEY, self.longitude ])
+          [ LATTITUDE_KEY, @lattitude ],
+          [ LONGITUDE_KEY, @longitude ])
       end
 
-      def self.from_h( point_hash ) # :nodoc:
+      # @param [Hash] point_hash
+      # @return [Point]
+      def self.from_h( point_hash ) 
         self.new( :lattitude => point_hash[ LATTITUDE_KEY ], :longitude => point_hash[ LONGITUDE_KEY ])
       end
     end

data/lib/rcap/cap_1_2/polygon.rb

@@ -6,25 +6,28 @@ module RCAP
     class Polygon
       include Validation
 
-      # Collection of Point objects.
+      # @return [Array<Point>] Collection of {Point} objects. 
       attr_reader( :points )
 
       validates_collection_of( :points )
       validates_length_of( :points, :minimum => 4 )
       validates_equality_of_first_and_last( :points )
 
-      XML_ELEMENT_NAME = 'polygon'                   # :nodoc:
-      XPATH            = "cap:#{ XML_ELEMENT_NAME }" # :nodoc:
-
+      XML_ELEMENT_NAME = 'polygon'                   
+      XPATH            = "cap:#{ XML_ELEMENT_NAME }" 
+      
+      # @param [Hash] attributes
+      # @option attributes [Array<Point>] :points Collection of {Point} objects
       def initialize( attributes = {})
         @points = Array( attributes[ :points ])
       end
 
-      # Creates a new Point object and adds it to the points array. The
-      # poitn_attributes are passed as a parameter to Point.new.
+      # Creates a new Point object and adds it to the points array.
+      #
+      # @see Point#initialize
       def add_point( point_attributes = {})
         point = Point.new( point_attributes )
-        self.points << point
+        @points << point
         point
       end
 
@@ -35,26 +38,37 @@ module RCAP
         @points.join( ' ' )
       end
 
-      def inspect # :nodoc:
+      # @return [String]
+      def inspect 
         "(#{ @points.map{|point| point.inspect}.join(', ')})"
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( XML_ELEMENT_NAME )
         xml_element.add_text( self.to_s )
         xml_element
       end
 
+      # @return [String]
+      def to_xml
+        self.to_xml_element.to_s
+      end
+
       # Two polygons are equivalent if their collection of points is equivalent.
+      # 
+      # @return [true,false]
       def ==( other )
-        self.points == other.points
+        @points == other.points
       end
 
-      def self.parse_polygon_string( polygon_string ) # :nodoc:
+      # @return [Array<Array(Numeric,Numeric)>]
+      def self.parse_polygon_string( polygon_string ) 
         polygon_string.split( ' ' ).map{ |coordinate_string| coordinate_string.split( ',' ).map{|coordinate| coordinate.to_f }}
       end
 
-      def self.from_xml_element( polygon_xml_element ) # :nodoc:
+      # @return [Polygon]
+      def self.from_xml_element( polygon_xml_element ) 
         if polygon_xml_element.text && !polygon_xml_element.text.empty?
           coordinates = self.parse_polygon_string( polygon_xml_element.text )
           points = coordinates.map{ |lattitude, longitude| Point.new( :lattitude => lattitude, :longitude => longitude )}
@@ -64,22 +78,25 @@ module RCAP
         end
       end
 
-
-      def to_yaml( options = {} ) # :nodoc:
-        self.points.map{ |point| [ point.lattitude, point.longitude ]}.to_yaml( options )
+      # @return [String]
+      def to_yaml( options = {} ) 
+        @points.map{ |point| [ point.lattitude, point.longitude ]}.to_yaml( options )
       end
 
-      def self.from_yaml_data( polygon_yaml_data ) # :nodoc:
+      # @return [Polygon]
+      def self.from_yaml_data( polygon_yaml_data ) 
         self.new( :points => Array( polygon_yaml_data ).map{ |lattitude, longitude| Point.new( :lattitude => lattitude, :longitude => longitude )})
       end
 
-      POINTS_KEY  = 'points' # :nodoc:
+      POINTS_KEY  = 'points' 
 
-      def to_h # :nodoc:
-        { POINTS_KEY => self.points.map{ |point| point.to_h }}
+      # @return [Hash]
+      def to_h 
+        { POINTS_KEY => @points.map{ |point| point.to_h }}
       end
 
-      def self.from_h( polygon_hash ) # :nodoc:
+      # @return [Polygon]
+      def self.from_h( polygon_hash ) 
         self.new( :points => polygon_hash[ POINTS_KEY ].map{ |point_hash| Point.from_h( point_hash )})
       end
     end

data/lib/rcap/cap_1_2/resource.rb

@@ -3,41 +3,49 @@ module RCAP
 
     # A Resource object is valid if
     # * it has a resource description
+    # * it has a mime_type
     class Resource
       include Validation
 
-      # Resource Description
+      # @return [String] Resource description 
       attr_accessor( :resource_desc )
-      # MIME type as described in RFC 2046
+      # @return [String] MIME type as described in RFC 2046 
       attr_accessor( :mime_type )
-      # Expressed in bytes
+      # @return [Integer] Expressed in bytes 
       attr_accessor( :size )
-      # Resource location
+      # @return [String] Resource location 
       attr_accessor( :uri )
-      # Dereferenced URI - contents of URI Base64 encoded
+      # @return [String] Dereferenced URI - contents of URI Base64 encoded 
       attr_accessor( :deref_uri )
-      # SHA-1 hash of contents of resource
+      # @return [String] SHA-1 hash of contents of resource 
       attr_accessor( :digest )
 
       validates_presence_of( :resource_desc )
       validates_presence_of( :mime_type )
 
-      XML_ELEMENT_NAME           = 'resource'     # :nodoc:
-      MIME_TYPE_ELEMENT_NAME     = 'mimeType'     # :nodoc:
-      SIZE_ELEMENT_NAME          = 'size'         # :nodoc:
-      URI_ELEMENT_NAME           = 'uri'          # :nodoc:
-      DEREF_URI_ELEMENT_NAME     = 'derefUri'     # :nodoc:
-      DIGEST_ELEMENT_NAME        = 'digest'       # :nodoc:
-      RESOURCE_DESC_ELEMENT_NAME = 'resourceDesc' # :nodoc:
-
-      XPATH               = "cap:#{ XML_ELEMENT_NAME }"           # :nodoc:
-      MIME_TYPE_XPATH     = "cap:#{ MIME_TYPE_ELEMENT_NAME }"     # :nodoc:
-      SIZE_XPATH          = "cap:#{ SIZE_ELEMENT_NAME }"          # :nodoc:
-      URI_XPATH           = "cap:#{ URI_ELEMENT_NAME }"           # :nodoc:
-      DEREF_URI_XPATH     = "cap:#{ DEREF_URI_ELEMENT_NAME }"     # :nodoc:
-      DIGEST_XPATH        = "cap:#{ DIGEST_ELEMENT_NAME }"        # :nodoc:
-      RESOURCE_DESC_XPATH = "cap:#{ RESOURCE_DESC_ELEMENT_NAME }" # :nodoc:
-
+      XML_ELEMENT_NAME           = 'resource'     
+      MIME_TYPE_ELEMENT_NAME     = 'mimeType'     
+      SIZE_ELEMENT_NAME          = 'size'         
+      URI_ELEMENT_NAME           = 'uri'          
+      DEREF_URI_ELEMENT_NAME     = 'derefUri'     
+      DIGEST_ELEMENT_NAME        = 'digest'       
+      RESOURCE_DESC_ELEMENT_NAME = 'resourceDesc' 
+
+      XPATH               = "cap:#{ XML_ELEMENT_NAME }"           
+      MIME_TYPE_XPATH     = "cap:#{ MIME_TYPE_ELEMENT_NAME }"     
+      SIZE_XPATH          = "cap:#{ SIZE_ELEMENT_NAME }"          
+      URI_XPATH           = "cap:#{ URI_ELEMENT_NAME }"           
+      DEREF_URI_XPATH     = "cap:#{ DEREF_URI_ELEMENT_NAME }"     
+      DIGEST_XPATH        = "cap:#{ DIGEST_ELEMENT_NAME }"        
+      RESOURCE_DESC_XPATH = "cap:#{ RESOURCE_DESC_ELEMENT_NAME }" 
+
+      # @param [Hash{Symbol => Object}] attributes
+      # @option attributes [String] :mime_type
+      # @option attributes [Numeric] :size Size in bytes
+      # @option attributes [String] :uri
+      # @option attributes [String] :deref_uri
+      # @option attributes [String] :digest
+      # @option attributes [String] :resource_desc
       def initialize( attributes = {} )
         @mime_type     = attributes[ :mime_type ]
         @size          = attributes[ :size ]
@@ -47,57 +55,83 @@ module RCAP
         @resource_desc = attributes[ :resource_desc ]
       end
 
-      def to_xml_element # :nodoc:
+      # @return [REXML::Element]
+      def to_xml_element 
         xml_element = REXML::Element.new( XML_ELEMENT_NAME )
-        xml_element.add_element( RESOURCE_DESC_ELEMENT_NAME ).add_text( self.resource_desc )
-        xml_element.add_element( MIME_TYPE_ELEMENT_NAME ).add_text( self.mime_type ) if self.mime_type
-        xml_element.add_element( SIZE_ELEMENT_NAME ).add_text( self.size.to_s )      if self.size
-        xml_element.add_element( URI_ELEMENT_NAME ).add_text( self.uri )             if self.uri
-        xml_element.add_element( DEREF_URI_ELEMENT_NAME ).add_text( self.deref_uri ) if self.deref_uri
-        xml_element.add_element( DIGEST_ELEMENT_NAME ).add_text( self.digest )       if self.digest
+        xml_element.add_element( RESOURCE_DESC_ELEMENT_NAME ).add_text( @resource_desc )
+        xml_element.add_element( MIME_TYPE_ELEMENT_NAME ).add_text( @mime_type ) if @mime_type
+        xml_element.add_element( SIZE_ELEMENT_NAME ).add_text( @size.to_s )      if @size
+        xml_element.add_element( URI_ELEMENT_NAME ).add_text( @uri )             if @uri
+        xml_element.add_element( DEREF_URI_ELEMENT_NAME ).add_text( @deref_uri ) if @deref_uri
+        xml_element.add_element( DIGEST_ELEMENT_NAME ).add_text( @digest )       if @digest
         xml_element
       end
 
       # If size is defined returns the size in kilobytes
+      # @return [Float]
       def size_in_kb
-        if self.size
-          self.size.to_f/1024
+        if @size
+          @size.to_f/1024
         end
       end
 
-      def to_xml # :nodoc:
+      # @return [String]
+      def to_xml 
         self.to_xml_element.to_s
       end
 
-      def inspect # :nodoc:
-        [ self.resource_desc, self.uri, self.mime_type, self.size ? format( "%.1fKB", self.size_in_kb ) : nil ].compact.join(' - ')
+      # @return [String]
+      def inspect 
+        [ @resource_desc, @uri, @mime_type, @size ? format( "%.1fKB", @size_in_kb ) : nil ].compact.join(' - ')
       end
 
       # Returns a string representation of the resource of the form
       #  resource_desc
+      #
+      # @return [String]
       def to_s
-        self.resource_desc
+        @resource_desc
       end
 
       # Retrieves the content at uri and stores it in deref_uri as Base64 encoded text. It will also
-      # calculate the digest on the encoded data using SHA1 and set the size.
+      # calculate the {#digest} on the encoded data using SHA1 and set the {#size}.
       #
       # This uses the open-uri[http://ruby-doc.org/stdlib/libdoc/open-uri/rdoc/index.html] Ruby API
-      # to open and read the content.
+      # to open and read the content. This method may throw an exception due to any number of network
+      # related issue so please handle accordingly.
+      #
+      # Returns an array containing the size (in bytes) and SHA-1 hash.
+      #
+      # @return [Array(Integer,String)]
       def dereference_uri!
         content = URI.parse( self.uri ).read
         @deref_uri = Base64.encode64( content )
         self.calculate_hash_and_size
       end
 
+      # Calculates the SHA-1 hash and size of the contents of {#deref_uri}.
+      # Returns an array containing the size (in bytes) and SHA-1 hash if
+      # {#deref_uri} is present otherwise returns nil.
+      #
+      # @return [nil,Array(Integer,String)]
       def calculate_hash_and_size
         if @deref_uri
           @digest = Digest::SHA1.hexdigest( @deref_uri )
           @size = @deref_uri.bytesize
+          [ @size, @digest ]
         end
       end
 
-      def self.from_xml_element( resource_xml_element ) # :nodoc:
+      # The decoded contents of {#deref_uri} if present otherwise nil.
+      #
+      # @return [nil,String]
+      def decoded_deref_uri
+        Base64.decode64( @deref_uri ) if @deref_uri
+      end
+
+      # @param [REXML::Element] resource_xml_element
+      # @return [Resource]
+      def self.from_xml_element( resource_xml_element ) 
         resource = self.new( :resource_desc => RCAP.xpath_text( resource_xml_element, RESOURCE_DESC_XPATH, Alert::XMLNS ),
                              :uri           => RCAP.xpath_text( resource_xml_element, URI_XPATH, Alert::XMLNS ),
                              :mime_type     => RCAP.xpath_text( resource_xml_element, MIME_TYPE_XPATH, Alert::XMLNS ),
@@ -106,25 +140,28 @@ module RCAP
                              :digest        => RCAP.xpath_text( resource_xml_element, DIGEST_XPATH, Alert::XMLNS ))
       end
 
-      RESOURCE_DESC_YAML = "Resource Description" # :nodoc:
-      URI_YAML           = "URI"                  # :nodoc:
-      MIME_TYPE_YAML     = "Mime Type"            # :nodoc:
-      DEREF_URI_YAML     = "Derefrenced URI Data" # :nodoc:
-      SIZE_YAML          = "Size"                 # :nodoc:
-      DIGEST_YAML        = "Digest"               # :nodoc:
+      RESOURCE_DESC_YAML = "Resource Description" 
+      URI_YAML           = "URI"                  
+      MIME_TYPE_YAML     = "Mime Type"            
+      DEREF_URI_YAML     = "Derefrenced URI Data" 
+      SIZE_YAML          = "Size"                 
+      DIGEST_YAML        = "Digest"               
 
-      def to_yaml( options = {} ) # :nodoc:
+      # @param [Hash] options
+      # @return [String]
+      def to_yaml( options = {} ) 
         RCAP.attribute_values_to_hash(
-          [ RESOURCE_DESC_YAML, self.resource_desc ],
-          [ URI_YAML,           self.uri ],
-          [ MIME_TYPE_YAML,     self.mime_type ],
-          [ DEREF_URI_YAML,     self.deref_uri ],
-          [ SIZE_YAML,          self.size ],
-          [ DIGEST_YAML,        self.digest ]
-        ).to_yaml( options )
+          [ RESOURCE_DESC_YAML, @resource_desc ],
+          [ URI_YAML,           @uri ],
+          [ MIME_TYPE_YAML,     @mime_type ],
+          [ DEREF_URI_YAML,     @deref_uri ],
+          [ SIZE_YAML,          @size ],
+          [ DIGEST_YAML,        @digest ]).to_yaml( options )
       end
 
-      def self.from_yaml_data( resource_yaml_data ) # :nodoc:
+      # @param [Hash] resource_yaml_data
+      # @return [Resource]
+      def self.from_yaml_data( resource_yaml_data ) 
         self.new(
           :resource_desc => reource_yaml_data[ RESOURCE_DESC_YAML ],
           :uri           => reource_yaml_data[ URI_YAML ],
@@ -135,24 +172,27 @@ module RCAP
         )
       end
 
-      RESOURCE_DESC_KEY = 'resource_desc' # :nodoc:
-      URI_KEY           = 'uri'           # :nodoc:
-      MIME_TYPE_KEY     = 'mime_type'     # :nodoc:
-      DEREF_URI_KEY     = 'deref_uri'     # :nodoc:
-      SIZE_KEY          = 'size'          # :nodoc:
-      DIGEST_KEY        = 'digest'        # :nodoc:
+      RESOURCE_DESC_KEY = 'resource_desc' 
+      URI_KEY           = 'uri'           
+      MIME_TYPE_KEY     = 'mime_type'     
+      DEREF_URI_KEY     = 'deref_uri'     
+      SIZE_KEY          = 'size'          
+      DIGEST_KEY        = 'digest'        
 
-      def to_h # :nodoc:
+      # @return [Hash]
+      def to_h 
         RCAP.attribute_values_to_hash(
-          [ RESOURCE_DESC_KEY, self.resource_desc ],
-          [ URI_KEY,           self.uri],
-          [ MIME_TYPE_KEY,     self.mime_type],
-          [ DEREF_URI_KEY,     self.deref_uri],
-          [ SIZE_KEY,          self.size ],
-          [ DIGEST_KEY,        self.digest ])
+          [ RESOURCE_DESC_KEY, @resource_desc ],
+          [ URI_KEY,           @uri],
+          [ MIME_TYPE_KEY,     @mime_type],
+          [ DEREF_URI_KEY,     @deref_uri],
+          [ SIZE_KEY,          @size ],
+          [ DIGEST_KEY,        @digest ])
       end
 
-      def self.from_h( resource_hash ) # :nodoc:
+      # @param [Hash] resource_hash
+      # @return [Resource]
+      def self.from_h( resource_hash ) 
         self.new(
           :resource_desc => resource_hash[ RESOURCE_DESC_KEY ],
           :uri           => resource_hash[ URI_KEY ],