adaptation 0.0.6 → 0.0.7

data/CHANGELOG

@@ -6,3 +6,5 @@
     - migrated to ActiveRrecord validations
 * 0.0.6
     - forced to use ROXML version 1.2
+* 0.0.7
+    - Documentation update + Message class clean up

data/README

@@ -36,14 +36,15 @@ adapting a database-backed application.
    By default this will try to subscribe to a mom listening on localhost:8080, using port
    8081 to subscribe. These values can be changed editing <tt>config/mom.yml</tt>. In mom.yml 
    you can also specify wich topics your adaptor is interested in.
-4. Start developing your adaptor, probably generating __Adaptors__, __Messages__ and __Models__.
+4. Start developing your adaptor, probably generating __Adaptors__[link:../rdoc/classes/Adaptation/Adaptor.html], __Messages__[link:../rdoc/classes/Adaptation/Message.html] 
+   and __Models__[http://api.rubyonrails.org/classes/ActiveRecord/Base.html].
 
 
 == Moms
 
 By default, Adaptation will try to use druby to execute the built-in Ruby mom. This
 mom is suitable for development, but not for production. For a production environment
-a more stable solution like Xmlblaster should be chosen. 
+a more stable solution like Xmlblaster[http://www.xmlblaster.org] should be chosen. 
 
 
 == Description of contents

data/lib/adaptation/adaptor.rb

@@ -3,7 +3,7 @@ module Adaptation
 #
 #Adaptation::Adaptor is the base class for those classes containing the logic to be executed when a message is read through the mom. 
 #
-#Each class extending Adaptation::Adaptor must implement the _process_ function, using it as the main entry point for the logic to be executed when a message arrives. The name of the class extending Adaptation::Message associates the class with the one to be executed when a message arrives. Ie. if a message is received with a root element named _<hello>_, adaptation will search for a class extending Adaptation::Adaptor named _HelloAdaptor_. 
+#Each class extending Adaptation::Adaptor must implement the _process_ function, using it as the main entry point for the logic to be executed when a message arrives. The name of the class extending Adaptation::Message associates the class with the one to be executed when a message arrives. Ie. if a message is received with a root element named <hello>, adaptation will search for a class extending Adaptation::Adaptor named _HelloAdaptor_. 
 #
 #<i>Adaptation::Adaptors</i> (classes extending Adaptation::Adaptor) must be stored under <i>app/adaptors_name</i> in the adaptation file tree. This is done automatically when an adaptor is generated using adaptation built-in generator:
 #  script/generate adaptor hello

data/lib/adaptation/message.rb

@@ -15,76 +15,83 @@ module Adaptation
 #
 #* Automated mapping between classes and xml attributes and elements.
 #
-#   class Contact < Adaptation::Message
-#     has_one :text, :name
-#   end
+#     class Contact < Adaptation::Message
+#       has_one :text, :name
+#     end
 #
-#   ...is automatically mapped to a xml structure with root element named "contact", such as:
+#  ...is automatically mapped to a xml structure with root element named "contact", such as:
 #
-#   <contact>
-#     <name>Name</name>
-#   </contact>
+#     <contact>
+#       <name>Name</name>
+#     </contact>
 #
-#   ...which gives Contact#name
+#  ...which gives Contact#name
 #
 #
 #* Associations between objects controlled by simple meta-programming macros.
 #
-#   class Agenda < Adaptation::Message
-#     has_one  :attribute, :type
-#     has_one  :text, :owner
-#     has_many :contacts
-#   end
+#     class Agenda < Adaptation::Message
+#       has_one  :attribute, :type
+#       has_one  :text, :owner
+#       has_many :contacts
+#     end
 #
-#   class Contact < Adaptation::Message
-#     has_one :text, :name
-#   end
+#     class Contact < Adaptation::Message
+#       has_one :text, :name
+#     end
 #
-#   Agenda class would be mapping the following xml structure:
+#  Agenda class would be mapping the following xml structure:
 #
-#   <agenda type="...">
-#     <owner>...</owner>
-#     <contact>...</contact>
-#     <contact>...</contact>
-#     ...
-#   </agenda>
+#     <agenda type="...">
+#       <owner>...</owner>
+#       <contact>...</contact>
+#       <contact>...</contact>
+#       ...
+#     </agenda>
 #
-#   while the _Contact_ class would map:
+#  while the _Contact_ class would map:
 #
-#   <contact>
-#     <name>...</name>
-#   </contact>
+#     <contact>
+#       <name>...</name>
+#     </contact>
 #
-#   The Contact class is a partial, a structure included in a bigger structure, so its 
-#   file name starts with an underscore: _contact.rb
+#  The Contact class is a partial, a structure included in a bigger structure, so its 
+#  file name starts with an underscore: _contact.rb
 #
-#   We could have wrote Agenda like this, to change the contacts container name:
+#  We could have wrote Agenda like this, to change the contacts container name:
 #
-#   class Agenda < Adaptation::Message
-#     has_one  :attribute, :type
-#     has_one  :text, :owner
-#     has_many :contacts, :in => :contact_list
-#   end
+#    class Agenda < Adaptation::Message
+#      has_one  :attribute, :type
+#      has_one  :text, :owner
+#      has_many :contacts, :in => :contact_list
+#    end
 #
-#   and Contact like:
+#  and Contact like:
 #
-#   class Contact < Adaptation::Message
-#     belongs_to :contact_list
-#     has_one :text, :name
-#   end
+#    class Contact < Adaptation::Message
+#      has_one :text, :name
+#    end
 # 
-#   Then the mapping in Agenda would be:
+#  Then the mapping in Agenda would be:
 #
-#   <agenda type="...">
-#     <owner>...</owner>
-#     <contact_list>
-#       <contact>...</contact>
-#     </contact_list>
-#   </agenda>
+#    <agenda type="...">
+#      <owner>...</owner>
+#      <contact_list>
+#        <contact>...</contact>
+#      </contact_list>
+#    </agenda>
 #
 #
 #* Validation rules.
 #
+#  Adaptation::Message uses {ActiveRecord::Validations}[http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html].
+#  This means that {ActiveRecord validations}[http://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html]
+#  can be used in an Adaptation::Message object and that custom validations can be easily implemented. 
+#  
+#  Adaptation::Message also defines some {custom validation methods}[link:../rdoc/classes/ActiveRecord/Validations/ClassMethods.html].
+#
+#  Validations usage example:
+#
 #    class Agenda < Adaptation::Message
 #      has_one :attribute, :type
 #      has_one :text, :owner
@@ -97,107 +104,46 @@ module Adaptation
     
     @@classes_with_brothers = []
     cattr_reader :classes_with_brothers
-    cattr_reader :validations
     cattr_reader :objects
     
     include Validateable
     include ROXML
 
-    def to_hash
-      s = self.to_yaml
-      h = YAML::load s[4..s.length].downcase.gsub(/\!ruby\/object:.* /,"")
-    end
-
-    def has_son?(son)
-      search_symbol_in_hash self.to_hash, son 
-    end
-
-    def search_symbol_in_hash hash, symbol
-      found = false
-      hash.each_pair do |k,v|
-        if (k.to_sym == symbol)
-          found = true
-          break
-        end
-      end
-      
-      if !found
-        hash.each_pair do |k,v|
-          found = search_symbol_in_hash(v, symbol) if v.is_a?(Hash)
-          break if found
-        end
-      end
-
-      found
-    end
-    
-    def search_paths(symbol)
-        get_paths_from_hash self.to_hash, symbol
-    end
-    
-    def search_objects(symbol)
-      objects = []  
-      paths = search_paths(symbol)
-      paths.each do |path|
-        objects << get_object(path)
-      end
-      objects.flatten
-    end
-    
-    def get_paths_from_hash hash, symbol, root_path = ""
-      paths = []
-      hash.each_pair do |k,v|
-        if (k.to_sym == symbol)  
-          paths << "#{root_path}.#{k}" unless paths.include?("#{root_path}.#{k}")
-        end
-      end
-      
-      hash.each_pair do |k,v|
-        if v.is_a?(Hash)  
-          son_paths = get_paths_from_hash(v, symbol, k)
-          son_paths.each do |sp|
-            paths << "#{root_path}.#{sp}" unless paths.include?("#{root_path}.#{sp}")
-          end  
-        elsif v.is_a?(Array)
-          v.each do |h|
-            son_paths = get_paths_from_hash(h, symbol, k)
-            son_paths.each do |sp|
-              paths << "#{root_path}.#{sp}" unless paths.include?("#{root_path}.#{sp}")
-            end 
-          end    
-        end
-      end
-
-      paths.map!{|p|
-        if p.first == "."
-          p[1..p.length]
-        else
-          p  
-        end
-      }
-      
-      paths
-    end
-    
-    def get_object path
-      subpaths = path.split(".")
-      objects = [self]
-      subpaths.each do |s|
-        array = []  
-        objects.each do |o|
-          if o.is_a?(Array)
-            o.each do |os|  
-              array << os.send(s.to_sym)
-            end  
-          else
-            array << o.send(s.to_sym)
-          end  
-        end
-        objects = array  
-      end
-      objects
-    end
 
+    # Maps an xml attribute or element.
+    # 
+    # Example 1: Mapping an attribute:
+    #   <xml attr="something"/>
+    #
+    #   class Xml < Adaptation::Message
+    #     has_one :attribute, :attr
+    #   end
+    #
+    # Example 2: Mapping an xml element that contains text.
+    #   <xml>
+    #     <element>something</element>
+    #   </xml>
+    #
+    #   class Xml < Adaptation::Message
+    #     has_one :text, :element
+    #   end
+    #
+    # Example 3: Mapping an xml element that contains xml data.
+    #   <xml>
+    #     <element>
+    #       <subelement>something</subelement>
+    #     </element>
+    #   </xml>
+    #
+    #   class Xml < Adaptation::Message
+    #     has_one :object, :element
+    #   end
+    #
+    # The element xml structure would be described in a separate partial file <em>_element.rb</em>:
+    #   class Element < Adaptation::Message
+    #     has_one :text, :subelement
+    #   end
+    #
     def self.has_one *symbols
       xml_tag = symbols[0]
       case xml_tag
@@ -233,6 +179,30 @@ module Adaptation
       end
     end
 
+    # Maps an xml element text.
+    #
+    # If an element contains plain text data and has not been declared in its parent element with
+    # <em>has_one :text</em>, it must declare itself with <em>has_text</em> to be able to contain text.
+    #
+    # Example:
+    #
+    #   <xml>
+    #     <element attr="something">something more</element>
+    #   </xml>
+    #
+    #   class Xml < Adaptation::Message
+    #     has_one :object, :element
+    #   end
+    #
+    # In this case element cannot be declared just like <em>has_one :text</em>, because it also has
+    # an attribute. It must be declared like <em>has_one :object</em>. Then the element declares itself
+    # in a file called <em>_element.rb</em> like this:
+    #
+    #   class Element < Adaptation::Message
+    #     has_one :attribute, :attr
+    #     has_text
+    #   end
+    # 
     def self.has_text
       if @has_text.nil?
         @has_text = true
@@ -240,20 +210,34 @@ module Adaptation
       end
     end
    
-    def self.has_brothers?
-      brothers_containers = []
-      @@classes_with_brothers.each do |cwb|
-        if cwb =~ /^#{self.to_s}:/   
-          brothers_containers << cwb    
-        end
-      end
-      if brothers_containers.empty?
-        return nil
-      else
-        return brothers_containers
-      end
-    end
-
+    # Maps many xml subelements.
+    #
+    # Example 1:
+    #
+    #   <xml>
+    #     <subelement>...</subelement>
+    #     <subelement>...</subelement>
+    #     <subelement>...</subelement>
+    #   </xml>
+    #
+    #   class Xml < Adaptation::Message
+    #     has_many :subelements
+    #   end   
+    #
+    # Example 2:
+    #
+    #   <xml>
+    #     <subelement_list>
+    #       <subelement>...</subelement>
+    #       <subelement>...</subelement>
+    #       <subelement>...</subelement>
+    #     </subelement_list>
+    #   </xml>       
+    #
+    #   class Xml < Adaptation::Message
+    #     has_many :subelements, :in => :subelement_list
+    #   end
+    #
     def self.has_many *options
       configuration = {}
       configuration.update(options.pop) if options.last.is_a?(Hash)
@@ -285,14 +269,22 @@ module Adaptation
       end
     end
 
-    def self.get_class_object(searched_class)
+    def self.get_class_object(searched_class) #:nodoc:
       Object.const_get searched_class
     end
-    
+   
+    # This is the constructor. Instead of <em>Adaptation::Message#new</em>, an <em>Adaptation::Message</em> 
+    # instance is created like this:
+    #
+    #   m = Adaptation::Message.to_object("<xml>valid xml</xml>")
+    #
     def self.to_object xml_message
       parse xml_message
     end
 
+    # Checks if an Adaptation::Message object passes all validations.
+    #
+    # It is an alias for <em>Adaptation::Message#valid?</em>
     def check
       valid?
     end

data/lib/adaptation/validateable.rb

@@ -19,6 +19,27 @@ module ActiveRecord
   module Validations
     module ClassMethods
 
+      # Validates whether the value of the specified xml attribute/element is the expected one.
+      #
+      # Example 1:
+      # 
+      #   <leftwing side="left"/>
+      #
+      #   class Leftwing < Adaptation::Message
+      #     has_one :attribute, :side
+      #
+      #     validates_value_of :side, "left"
+      #   end
+      # 
+      # Example 2:
+      #   <bird><wings><wing side="left"/><wing side="right"/></wings></bird>
+      #
+      #   class Bird < Adaptation::Message
+      #     has_many :wings
+      #
+      #     validates_value_of :side, "left", :in => :wings
+      #   end
+      #
       def validates_value_of(*attr_names)
         configuration = {
           :message => 'value doesn\'t exist' 
@@ -44,7 +65,18 @@ module ActiveRecord
           end
         end
       end
-
+      
+      # Validates whether the value of the specified xml attribute/element has a valid email format.
+      #
+      # Example:
+      #   <contact email="mail@xample.com">...</contact>
+      #
+      #   class Contact < Adaptation::Message
+      #     has_one :attribute, :email
+      #
+      #     validates_as_email :email
+      #   end  
+      #
       def validates_as_email(*attr_names)
         configuration = {
           :message   => 'is an invalid email',

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: adaptation
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
-date: 2008-07-24 00:00:00 +02:00
+  version: 0.0.7
+date: 2008-11-24 00:00:00 +01:00
 summary: Framework to facilitate web-application interaction.
 require_paths: 
 - lib
@@ -15,7 +15,7 @@ description: Adaptation is a framework for building "adaptors" for web-applicati
 autorequire: adaptation
 default_executable: adaptation
 bindir: bin
-has_rdoc: false
+has_rdoc: true
 required_ruby_version: !ruby/object:Gem::Version::Requirement 
   requirements: 
   - - ">"