acts_as_sdata 1.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+nbproject
+.idea

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,200 @@
+h1. acts_as_sdata
+
+Ruby implementation of SData (Sage Data) protocol. Rails plugin which enables SData syndication and publishing.
+
+h2. Demo
+
+Let's consider we want to expose the list of US presidents in SData way (this is exactly what is done in "presidents":http://github.com/DanielVartanov/acts_as_sdata-examples/tree/master/presidents/ application in "acts_as_sdata-examples":http://github.com/DanielVartanov/acts_as_sdata-examples repository).
+
+From client side it will look like this:
+
+h3. Instance path
+
+<code>http://localhost:3000/presidents/!Wilson</code>
+
+<pre><?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns="http://www.w3.org/2005/Atom" xmlns:attributes="http://sdata.sage.com/schemes/attributes">
+  <title>Wilson, Woodrow</title>
+  <summary>Wilson, Woodrow (1856-1924)</summary>
+  <attributes:born_at>1856</attributes:born_at>
+  <attributes:id>28</attributes:id>
+  <attributes:first_name>Woodrow</attributes:first_name>
+  <attributes:last_name>Wilson</attributes:last_name>
+  <attributes:party>Democrat</attributes:party>
+  <attributes:updated_at>Sat Jan 09 11:43:11 UTC 2010</attributes:updated_at>
+  <attributes:died_at>1924</attributes:died_at>
+  <attributes:order>28</attributes:order>
+  <attributes:term_started_at>1913</attributes:term_started_at>
+  <attributes:created_at>Sat Jan 09 11:43:11 UTC 2010</attributes:created_at>
+  <attributes:country>USA</attributes:country>
+  <attributes:term_ended_at>1921</attributes:term_ended_at>
+</entry></pre>
+
+h3. Collection path
+
+<code>http://localhost:3000/presidents</code>
+
+<pre><?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
+  <title>List of US presidents</title>
+  <updated>2009-11-17T10:55:28+06:00</updated>
+  <link href="http://example.com/presidents"/>
+  <author>
+    <name>Sage</name>
+  </author>
+  <entry>
+    <title>Washington, George</title>
+    <summary>Washington, George (1732-1799)</summary>
+  </entry>
+  <entry>
+    <title>Adams, John</title>
+    <summary>Adams, John (1735-1826)</summary>
+  </entry>
+.....
+</pre>
+
+h3. Predicate
+
+<code>http://localhost:3000/presidents(born_at gt 1900)</code>
+
+<pre><?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
+  <title>List of US presidents</title>
+  <updated>2009-11-17T10:58:15+06:00</updated>
+  <link href="http://example.com/presidents"/>
+  <author>
+    <name>Sage</name>
+  </author>
+  <entry>
+    <title>Kennedy, John</title>
+    <summary>Kennedy, John (1917-1963)</summary>
+  </entry>
+  <entry>
+    <title>Johnson, Lyndon</title>
+    <summary>Johnson, Lyndon (1908-1973)</summary>
+  </entry>
+.....
+</pre>
+
+h3. Publishing
+
+SData protocol supports data publishing (as Atom Publishing Protocol does)
+
+Example:
+
+<pre>require 'atom/pub'
+
+collection = Atom::Pub::Collection.new(:href => 'http://localhost:3000/presidents')
+
+entry = Atom::Entry.load_entry <<XML
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns="http://www.w3.org/2005/Atom" xmlns:attributes="http://sdata.sage.com/schemes/attributes">
+  <attributes:born_at>1961</attributes:born_at>
+  <attributes:first_name>Barack</attributes:first_name>
+  <attributes:last_name>Obama</attributes:last_name>
+  <attributes:party>Democrat</attributes:party>
+  <attributes:died_at/>
+  <attributes:order>44</attributes:order>
+  <attributes:term_started_at>2009</attributes:term_started_at>
+  <attributes:country>USA</attributes:country>
+  <attributes:term_ended_at/>
+</entry>
+XML
+
+collection.publish entry</pre>
+
+The response will be:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<entry xmlns="http://www.w3.org/2005/Atom" xmlns:attributes="http://sdata.sage.com/schemes/attributes">
+  <attributes:id>46</attributes:id>
+  <attributes:created_at>Sat Jan 09 14:29:57 UTC 2010</attributes:created_at>
+  <attributes:first_name>Barack</attributes:first_name>
+  ...
+</entry></pre>
+_with status 201 (Created)_
+
+h2. How to install
+
+h3. Install Usher
+
+_(Usher is an alternative router)_
+
+It is better to refer to "Usher's page":http://github.com/joshbuddy/usher/, but usually installation of Usher plugin is just one commad:
+
+<code>$ script/plugin install git://github.com/joshbuddy/usher.git</code>
+
+h3. Install acts_as_sdata
+
+<code>$ script/plugin install git://github.com/DanielVartanov/acts_as_sdata.git</code>
+
+h2. How to use
+
+In order to make application act as SData you should write the following.
+
+h3. In router
+
+<code>map.sdata_resource :presidents</code>
+_this line will enable all SData-related paths for /presidents_
+
+Also you should include special routing delimiters which are used in SData paths (remember, we are using Usher, this will _NOT_ work with native Rails Router).
+
+Change
+<code>ActionController::Routing::Routes.draw do |map|</code>
+to
+<code>ActionController::Routing::Routes.draw(:delimiters => ['/', '.', '!', '\(', '\)' ]) do |map|</code>
+
+h3. In controller
+
+<pre>acts_as_sdata :model => President,
+              :feed => { :id => 'urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6',
+                          :author => 'Sage',
+                          :path => '/presidents',
+                          :title => 'List of US presidents' }</pre>
+_<code>:feed</code> options defines fields of Atom feed_
+
+h3. In model
+
+<pre>acts_as_sdata :title => lambda { "#{last_name}, #{first_name}" },
+              :summary => lambda { "#{last_name}, #{first_name} (#{born_at}-#{died_at})" },
+              :instance_id => :last_name</pre>
+
+_Note #1: these lambda's will be executed in context of the actual model instance._
+
+_Note #2: SData specifications say that human-readable instance id's are preferred. The <code>:instance_id</code> option helps to enable search by any unique attribute._
+
+h3. Initializer
+
+In config/initializers/mime_types.rb add the following:
+
+<pre>ActionController::Base.param_parsers[Mime::Type.lookup('application/atom+xml')] = Proc.new do |data|
+  { :entry => Atom::Entry.load_entry(data) }
+end</pre>
+
+h2. Removing ambiguity
+
+h3. Problem
+
+There is an ambigious path in case of exposing same resource in both REST and SData ways:
+
+<code>/presidents</code>
+
+It might be treated either as #index (REST way) or as #sdata_collection (SData way).
+
+h3. Solution
+
+In order to remove this ambiguity, a :formatted_paths option can be given as a second parameter to #sdata_resource in routes.rb:
+
+<code>map.sdata_resource :presidents, :formatted_paths => true</code>
+
+Then,
+<code>/presidents</code> routes to Presidents#index and returns HTML
+<code>/presidents.sdata</code> routes to Presidents#sdata_collection and returns Atom/XML
+
+<i>without any changes in the controller code!</i>
+
+Copyright Sage 2009
+Released under the MIT license

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "acts_as_sdata"
+    gemspec.version = '1.0.0'
+    gemspec.authors = ["Daniel Vartanov", "Eugene Gilburg", "Michael Johnston"].sort
+    gemspec.email = "dan@vartanov.net"
+    gemspec.homepage = "http://sdata.sage.com/"
+    gemspec.summary = gemspec.description = "Ruby implementation of SData (Sage Data) protocol"
+    gemspec.has_rdoc = false
+    gemspec.extra_rdoc_files = ["README.textile"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/config/sdata.yml

@@ -0,0 +1,13 @@
+schemas:
+  xs: http://www.w3.org/2001/XMLSchema
+  cf: http://www.microsoft.com/schemas/rss/core/2005
+  sme: http://schemas.sage.com/sdata/sme/2007
+  sc: http://schemas.sage.com/sc/2009
+  http: http://schemas.sage.com/sdata/http/2008/1
+  sync: http://schemas.sage.com/sdata/sync/2008/1
+  opensearch: http://a9.com/-/spec/opensearch/1.1/
+  sdata: http://schemas.sage.com/sdata/2008/1
+  xsi: http://www.w3.org/2001/XMLSchema-instance
+  sle: http://www.microsoft.com/schemas/rss/core/2005
+
+show_stack_trace: true

data/config/sdata.yml.example

@@ -0,0 +1,20 @@
+# example of app config adding to or overriding the standard plugin config
+
+# required: at least 1 contract
+schemas:
+  crmErp:         http://schemas.sage.com/crmErp/2008
+
+# required, the host-with-protocol of your server
+base_url:         http://example.com
+# your sdata application name (required in sdata urls)
+application:      billingboss
+# the default contract supported by your app (required in sdata urls)
+contracts:        
+  - crmErp
+  - bb
+
+# default is 0, lower gets priority
+sync_endpoint_conflict_priority: 10
+
+# optional
+show_stack_trace: true

data/config/sdata.yml.tmpl.staging

@@ -0,0 +1,14 @@
+schemas:
+  xs: http://www.w3.org/2001/XMLSchema
+  cf: http://www.microsoft.com/schemas/rss/core/2005
+  sme: http://schemas.sage.com/sdata/sme/2007
+  sc: http://schemas.sage.com/sc/2009
+  http: http://schemas.sage.com/sdata/http/2008/1
+  sync: http://schemas.sage.com/sdata/sync/2008/1
+  opensearch: http://a9.com/-/spec/opensearch/1.1/
+  sdata: http://schemas.sage.com/sdata/2008/1
+  xsi: http://www.w3.org/2001/XMLSchema-instance
+  sle: http://www.microsoft.com/schemas/rss/core/2005
+
+show_stack_trace: true
+

data/generators/acts_as_sdata/acts_as_sdata_generator.rb

@@ -0,0 +1,9 @@
+class ActsAsSdataGenerator < Rails::Generator::Base  
+  def manifest
+    record do |m|
+      m.migration_template "migration.rb", 'db/migrate',
+                           :migration_file_name => "create_sdata_database_tables"
+    end
+  end
+  
+end

data/generators/acts_as_sdata/templates/migration.rb

@@ -0,0 +1,69 @@
+create_table "sd_digest_entries", :force => true do |t|
+  t.integer  "sd_digest_id"
+  t.integer  "tick"
+  t.string   "endpoint"
+  t.integer  "conflict_priority"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+end
+
+add_index "sd_digest_entries", ["sd_digest_id", "endpoint"], :name => "index_sd_digest_entries_on_sd_digest_id_and_endpoint", :unique => true
+
+create_table "sd_digests", :force => true do |t|
+  t.integer  "created_by_id"
+  t.string   "sd_class"
+  t.datetime "locked_at"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+end
+
+add_index "sd_digests", ["created_by_id", "sd_class"], :name => "index_sd_digests_on_created_by_id_and_sd_class", :unique => true
+
+create_table "sd_sync_runs", :force => true do |t|
+  t.integer  "created_by_id"
+  t.string   "tracking_id"
+  t.string   "run_name"
+  t.integer  "lock_version"
+  t.string   "sd_class"
+  t.string   "sync_mode"
+  t.text     "objects_data",       :limit => 2147483647
+  t.text     "target_digest_data"
+  t.text     "source_digest_data"
+  t.string   "phase"
+  t.string   "phase_detail"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+end
+
+create_table "sd_sync_states", :force => true do |t|
+  t.integer  "sd_digest_id"
+  t.integer  "sd_uuid_id"
+  t.integer  "tick"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+  t.string   "endpoint"
+end
+
+add_index "sd_sync_states", ["sd_digest_id", "sd_uuid_id"], :name => "index_sd_sync_states_on_sd_digest_id_and_sd_uuid_id", :unique => true
+
+create_table "sd_ticks", :force => true do |t|
+  t.integer  "user_id"
+  t.integer  "tick"
+  t.datetime "locked_at"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+end
+
+add_index "sd_ticks", ["user_id"], :name => "index_sd_ticks_on_user_id", :unique => true
+
+create_table "sd_uuids", :force => true do |t|
+  t.string   "sd_class"
+  t.integer  "bb_model_id"
+  t.string   "bb_model_type"
+  t.string   "uuid"
+  t.datetime "created_at"
+  t.datetime "updated_at"
+end
+
+add_index "sd_uuids", ["sd_class", "bb_model_type", "uuid"], :name => "index_sd_uuids_on_sd_class_and_bb_model_type_and_uuid", :unique => true
+

data/init.rb

@@ -0,0 +1,36 @@
+# RADAR: The order makes a difference, and globbing Dir produces different results on different machines.
+# We can .sort the glob, but still the order would be wrong, and we'd need to have repeated requires in
+# Individual files. Michael and I think it's easier to statically call them all in one place in the right order.
+
+__DIR__ = File.dirname(__FILE__)
+require File.join(__DIR__, 'lib', 's_data')
+require File.join(__DIR__, 'lib', 's_data', 'exceptions')
+require File.join(__DIR__, 'lib', 's_data', 'formatting.rb')
+require File.join(__DIR__, 'lib', 's_data', 'router_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'sync', 'sdata_syncing_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'sync', 'controller_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'payload_map.rb')
+require File.join(__DIR__, 'lib', 's_data', 'controller_mixin', 's_data_instance.rb')
+require File.join(__DIR__, 'lib', 's_data', 'controller_mixin', 's_data_feed.rb')
+require File.join(__DIR__, 'lib', 's_data', 'controller_mixin', 'collection_scope.rb')
+require File.join(__DIR__, 'lib', 's_data', 'controller_mixin', 'actions.rb')
+require File.join(__DIR__, 'lib', 's_data', 'atom_extensions', 'nodes', 'digest.rb')
+require File.join(__DIR__, 'lib', 's_data', 'atom_extensions', 'nodes', 'payload.rb')
+require File.join(__DIR__, 'lib', 's_data', 'atom_extensions', 'nodes', 'sync_state.rb')
+require File.join(__DIR__, 'lib', 's_data', 'payload.rb')
+require File.join(__DIR__, 'lib', 's_data', 'route_mapper.rb')
+require File.join(__DIR__, 'lib', 's_data', 'atom_extensions', 'content_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'atom_extensions', 'entry_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'namespace_definitions.rb')
+require File.join(__DIR__, 'lib', 's_data', 'predicate.rb')
+require File.join(__DIR__, 'lib', 's_data', 'active_record_extensions', 'mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'active_record_extensions', 'sdata_uuid_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'active_record_extensions', 'base.rb')
+require File.join(__DIR__, 'lib', 's_data', 'virtual_base.rb')
+require File.join(__DIR__, 'lib', 's_data', 'conditions_builder.rb')
+require File.join(__DIR__, 'lib', 's_data', 'controller_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'payload_map', 'payload_map_hash.rb')
+require File.join(__DIR__, 'lib', 's_data', 'payload_map', 'payload_map.rb')
+require File.join(__DIR__, 'lib', 's_data', 'diagnosis', 'diagnosis.rb')
+require File.join(__DIR__, 'lib', 's_data', 'diagnosis', 'application_controller_mixin.rb')
+require File.join(__DIR__, 'lib', 's_data', 'diagnosis', 'diagnosis_mapper.rb')

data/lib/s_data/active_record_extensions/base.rb

@@ -0,0 +1,7 @@
+module SData
+  module ActiveRecordExtensions
+    class Base < ::ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/lib/s_data/active_record_extensions/mixin.rb

@@ -0,0 +1,157 @@
+require 'forwardable'
+
+module SData
+  module ActiveRecordExtensions  
+    module Mixin
+      def acts_as_sdata(options={})
+        cattr_accessor :sdata_options
+        self.sdata_options = options
+        self.__send__ :include, InstanceMethods
+        self.__send__ :extend, ClassMethods
+      end
+
+      def find_by_sdata_instance_id(value)
+        attribute = self.sdata_options[:instance_id]
+
+        attribute.nil? ?
+          self.find(value.to_i) :
+          self.first(:conditions => { attribute => value })
+      end
+
+      module ClassMethods
+      
+        def sdata_node_name(entity=self)
+          self.name.demodulize.camelize(:lower)
+        end  
+
+        def sdata_contract_name
+          SData.sdata_contract_name(self.name)
+        end
+      
+        def sdata_resource_kind_url(dataset)
+          #FIXME: will change when we support bk use cases
+          postfix = self.sdata_node_name.pluralize
+          "#{SData.endpoint}/#{dataset}/#{postfix}"
+        end
+
+        def sdata_date(date_time)
+          SData::Formatting.format_date_time(date_time)
+        end
+
+      end
+
+      module InstanceMethods
+        def to_atom(params={}, opts={})
+          opts = {
+            :atom_show_categories => true,
+            :atom_show_links => true,
+            :atom_show_authors => true
+          }.merge(opts)
+          maximum_precedence = (!params[:precedence].blank? ? params[:precedence].to_i : 100)
+          included = params[:include].to_s.split(',')
+          selected = params[:select].to_s.split(',')
+          dataset = params[:dataset] #Maybe || '-' but I don't think it's a good idea to imply a default dataset at this level
+          
+          query = "?#{clean_params(params).to_query}".chomp('?')
+          sync = (params[:sync].to_s == 'true')
+          expand = ((sync || included.include?('$children')) ? :all_children : :immediate_children)
+          
+          returning Atom::Entry.new do |entry|
+            entry.id = self.sdata_resource_url(dataset)
+            entry.title = entry_title
+            entry.updated = self.class.sdata_date(self.updated_at)
+            entry.authors << Atom::Person.new(:name => self.respond_to?('author') ? self.author : sdata_default_author)  if opts[:atom_show_authors]
+            entry.links << Atom::Link.new(:rel => 'self', 
+                                          :href => "#{self.sdata_resource_url(dataset)}#{query}", 
+                                          :type => 'application/atom+xml; type=entry', 
+                                          :title => 'Refresh') if opts[:atom_show_links] 
+            entry.categories << Atom::Category.new(:scheme => 'http://schemas.sage.com/sdata/categories',
+                                                     :term   => self.sdata_node_name,
+                                                     :label  => self.sdata_node_name.underscore.humanize.titleize) if opts[:atom_show_categories] 
+                                                   
+            yield entry if block_given?
+          
+            if maximum_precedence > 0
+              begin
+                payload = Payload.new(:included => included, 
+                                        :selected => selected, 
+                                        :maximum_precedence => maximum_precedence, 
+                                        :sync => sync,
+                                        :contract => self.sdata_contract_name,
+                                        :entity => self,
+                                        :expand => expand,
+                                        :dataset => dataset)
+                payload.generate!
+                entry.sdata_payload = payload
+              rescue Exception => e
+                entry.diagnosis = Atom::Content::Diagnosis.new(ApplicationDiagnosis.new(:exception => e).to_xml(:entry))
+              end
+            end
+            entry.content = sdata_content
+          end
+        end
+
+        def sdata_name
+          self.class.name.demodulize
+        end
+
+        def sdata_node_name(entity=self.class)
+          self.class.sdata_node_name(entity)
+        end
+
+        def sdata_resource_url(dataset)
+          self.class.sdata_resource_kind_url(dataset) + "('#{self.id}')"
+        end
+
+        def resource_header_attributes(dataset, included)
+          hash = {}
+          hash.merge!({"sdata:key" => self.id, "sdata:url" => self.sdata_resource_url(dataset)}) if self.id
+          hash.merge!("sdata:descriptor" => self.entry_content) if included.include?("$descriptor")
+          hash.merge!("sdata:uuid" => self.uuid.to_s) if self.respond_to?("uuid") && !self.uuid.blank?
+          hash
+        end
+      
+        protected
+
+        def sdata_contract_name
+          self.class.sdata_contract_name
+        end
+        
+        def sdata_default_author
+          "Billing Boss"
+        end
+
+        def entry_title
+          title_proc = self.sdata_options[:title]
+          title_proc ? instance_eval(&title_proc) : default_entity_title
+        end
+
+        def default_entity_title
+          "#{self.class.name.demodulize.titleize} #{id}"
+        end
+
+        def entry_content
+          content_proc = self.sdata_options[:content]
+          content_proc ? instance_eval(&content_proc) : default_entry_content
+        end
+              
+        def default_entry_content
+          self.class.name
+        end
+        
+        # Thought about passing query_params from controller so wouldn't need this, but it causes other problems
+        # (dataset needs to be passed)
+        def clean_params(params)
+          params.stringify_keys.reject{|key,value|['action','controller','instance_id','dataset'].include?(key)}
+        end
+
+      end
+    end
+  end
+end
+# Extension of ActiveRecord removed due to refactoring. Now SData::VirtualBase is extended instead.
+# Not sure yet if there is a case where we DO need to extend ActiveRecord directly.
+# Might considering merging those two classes otherwise.
+# RADAR: Tested refactoring, but it could still be buggy if I missed something! Watch out.
+
+