rubyrest 0.0.5 → 0.1.0

data/CHANGELOG

@@ -1,9 +1,13 @@
-== What's next?
+== Release 0.1.0
 
-* Introduce the concept of 'security authority' so that multiple deployed instances of rubyrest can be federated by a single authentication and authorization service.
-* Use mongrel as the HTTP server implementation, instead of WEBrick
-* Refactor code, style it more 'a la' Ruby.
-* Provide more complex examples, such as Database Configurations
+* A rewritten from scratch architecture and implementation that offers: pluggability, better object orientation, thread safety and backwards incompatibility (sorry for this one!)
+* A clear separation between the REST Resource, the Model and the Service
+* A new domain specific language of declarative rules for  Atom data binding and formatting
+* Built-in Sequel (http://sequel.rubyforge.org) and PostgreSQL application support
+
+== Release 0.0.6
+
+* In Atom Entry related links, the #atom_related method must now return an array of hashes with the following keys: title (instead of model), type. A new type is now supported: 'action'.
 
 == Release 0.0.5
 

data/README

@@ -8,15 +8,14 @@ lets you create new REST services without too much effort.
 
 == Resources
 
-* {Project Documentation}[http://rubyrest.rubyforge.org]
 * {Project Page at Rubyforge}[http://rubyforge.org/projects/rubyrest]
-* {Project Page at Google Code}[http://code.google.com/p/rubyrest]
+* {Developer blog}[http://www.moodisland.com]
 
 To check out the source code:
   
   svn checkout svn://rubyforge.org/var/svn/rubyrest/trunk
   
-=== Contact
+== Contact
 
 If you have any comments or suggestions please send an email to pedro dot gutierrez at netcourrier dot com and I'll get back to you.
 
@@ -24,13 +23,13 @@ If you have any comments or suggestions please send an email to pedro dot gutier
 
   sudo gem install rubyrest
   
-== Getting Started
-
 === Learning by example
 
-Please have a look at the examples provided, they are simple enough to let you grasp how rubyrest works.
+Maybe the easiest way to learn how Ruby-on-Rest works is to take a look at the following examples, included in the source distribution:
+
+* The 'Hello' application can be used as a skeletton for new Ruby-on-Rest applications
 
-=== Starting the service
+== Starting the service
 
 Ruby-on-Rest provides a shell command. Open your console, and type the following:
  
@@ -40,15 +39,20 @@ Ruby-on-Rest provides a shell command. Open your console, and type the following
 This will first look at a YAML file called <my_service>_dev.yaml or <my_service>_live.yaml under the 
 current path.
 
-Ruby-on-Rest can also be embedded in ruby code. This is useful for testing purposes:
+== Embedding the Ruby-on-Rest engine
+
+Ruby-on-Rest can be embedded in Ruby code. This is useful for testing purposes:
 	
   config = {
-	"service" => "hello",
-	"prefix" => "acme",
-	"serviceport" => 9003
-	"daemon" => true
-	"entities" => [ "welcomeservice" ]
-  }	
+
+  	"module" => "acme",
+  	"service" => "hello",
+  	"version" => "v1.0",
+  	"webserver" => :webrick,
+  	"destroy" => false ,
+  	"daemon" => true,
+  	"http_port" => 10000
+  }
 	
   engine = RubyRest::Engine.new( config )
   engine.start
@@ -56,12 +60,3 @@ Ruby-on-Rest can also be embedded in ruby code. This is useful for testing purpo
   # do some http calls here
   # ...
   engine.stop
-
-
-=== Configuring your service
-
-Ruby-on-Rest will try to load a file name <my_service>.rb which provides the implementation of the service.
-
-
-
-

data/Rakefile

@@ -6,7 +6,7 @@ require 'fileutils'
 include FileUtils
 
 NAME = "rubyrest"
-VERS = "0.0.5"
+VERS = "0.1.0"
 CLEAN.include ['**/.*.sw?', 'pkg/*', '.config', 'doc/*', 'coverage/*']
 RDOC_OPTS = ['--quiet', '--title', "Ruby-on-Rest: A simple REST framework for Ruby",
   "--opname", "index.html",
@@ -25,7 +25,7 @@ Rake::RDocTask.new do |rdoc|
   rdoc.options += RDOC_OPTS
   rdoc.main = "README"
   rdoc.title = "Ruby-on-Rest Documentation"
-  rdoc.rdoc_files.add ['README', 'COPYING', "CHANGELOG", 'lib/rubyrest.rb', 'lib/rubyrest/**/*.rb', 'examples/**/*.rb' ]
+  rdoc.rdoc_files.add ['README', 'COPYING', "CHANGELOG", 'lib/rubyrest.rb', 'lib/rubyrest/**/*.rb' ]
 end
 
 spec = Gem::Specification.new do |s|
@@ -33,8 +33,8 @@ spec = Gem::Specification.new do |s|
   s.version = VERS
   s.platform = Gem::Platform::RUBY
   s.has_rdoc = true
-  s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING", 'examples/hello.rb' ]
-  s.rdoc_options += RDOC_OPTS + [ '--exclude', 'lib/rubyrest.rb', '--include', 'examples/*.rb' ]
+  s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING" ]
+  s.rdoc_options += RDOC_OPTS + [ '--exclude', 'lib/rubyrest.rb' ]
   s.summary = "REST framework for Ruby."
   s.description = s.summary
   s.author = "Pedro Gutierrez"

data/lib/rubyrest/application.rb

@@ -0,0 +1,221 @@
+module RubyRest
+    
+    # Base Application class for all applications deployed
+    # with Ruby-on-Rest
+    class Application
+      attr_reader :config
+      
+      # Defines whether update and create operations should
+      # automatically load and create new domain model, and automatically
+      # bind values from the request body document. Can be disabled
+      # in subclasses.
+      def auto_bind; true end
+      
+      # To be overriden by applications that use databases 
+      def init_database
+      
+      end
+      
+      def initialize( config )
+        @config = config
+        setup
+        register_model
+        register_resources
+        register_formatters
+        init_database
+      end
+      
+      # Loads all the domain files provided by the developer
+      def register_model
+        path_to_model = @doc_base + "/domain"
+        Dir.foreach( path_to_model ) { |filename|
+          filename = File.basename( filename, ".rb" )
+          if !(File.basename( filename )[0] == ?.) && !FileTest.directory?( filename )
+            require path_to_model + "/" + filename
+          end
+        }
+      end
+      
+      # Loads all the resources configured under the 'resources'
+      # folder relative to the application doc base
+      def register_resources
+        @resources_by_path = Hash.new 
+        @resources_by_model = Hash.new 
+        path_to_resources = @doc_base + "/resources"
+        
+        Dir.foreach( @doc_base + "/resources" ) { |filename|
+          if !(File.basename( filename )[0] == ?.) && !FileTest.directory?( filename )
+            filename = File.basename( filename, ".rb" )
+            require path_to_resources + "/" + filename
+            register_resource( to_resource_class( filename ).new( self ) )
+          end
+        }
+      end
+      
+      # Please override me if needed
+      def setup
+        
+      end
+      
+      # Returns the description and version
+      def to_s
+        @config[:service] + " " + @config[:version]
+      end
+      
+      # Resolves the Ruby-on-Rest resource descriptor for the 
+      # specified request path
+      def resource_for_path( path )
+        mount_point = "/"
+        path_tokens = path.split( "/" )
+        mount_point = "/"+path_tokens[1] if path_tokens.length > 0
+        resource = @resources_by_path[mount_point]
+        raise "no resource mounted at #{mount_point}" if !resource
+        return resource
+      end
+      
+      # Retrieves the Ruby-on-Rest resource descriptor for the specified
+      # model object
+      def resource_for_model( model )
+        resource = @resources_by_model[model.class]
+        raise "no resource mounted for model #{model.class}" if !resource
+        return resource
+      end
+      
+      # Registers a new resource instance
+      def register_resource( resource )
+        @resources_by_path[resource.class.mount_point] = resource
+        @resources_by_model[resource.model]=resource.class
+        puts "resource mounted: #{resource}"
+      end
+      
+      # Returns the class name for the given resource name
+      def to_resource_class( name )
+        Class.by_name( @config[:module].capitalize + "::" + @config[:service].capitalize + "::" + name.to_s.capitalize )
+      end
+      
+      # Register all the formatters supported by the application
+      # For the moment, only the Atom representation of resources
+      # is supported
+      def register_formatters
+        @formatters = { :atom => RubyRest::Atom::Formatter.new( self ) }
+      end
+      
+      # Resolves the formatter to use in the returned
+      # representation
+      def formatter( params )
+        @formatters[params[:format]]||@formatters[:atom]
+      end
+      
+      # Invoked by the web layer, on a DELETE request
+      def delete( params )
+        res = resource_for_path( params[:path] )
+        res.service.delete( res.service.load( params[:target], params[:principal] ), params[:principal] )
+      end
+      
+      def render_model( params, model )
+        formatter( params ).format( model, params )
+      end
+      
+      # Invoked by the web layer, on a GET request. 
+      # Retrieves the collection or resource, and formats the 
+      # result as a feed, entry or service document
+      def retrieve( params )
+        res = resource_for_path( params[:path] )
+        if params[:target] == nil
+          objects = res.service.list( params[:principal] )
+        else
+          if params[:property] == nil
+            objects = res.service.load( params[:target], params[:principal] )
+          else
+            objects = res.service.list_related( params[:target], params[:property], params[:principal] )
+          end
+        end
+        render_model( params, objects )
+      end
+      
+      # Invoked by the web layer, on a POST request.
+      # This method delegates to the resource's service and provides 
+      # a fresh new model object populated with the data 
+      # found in the request body.
+      def create( params )
+        res = resource_for_path( params[:path] )
+        params[:body] = res.bind( res.service.create( params[:principal] ), params[:body] ) if auto_bind == true
+        object = res.service.save_new( params[:body], params[:principal] )
+        render_model( params, object )
+      end
+      
+      # Invoked by the web layer, on a PUT request
+      # This method delegates to the resource's service and provides an existing model
+      # object, loaded and populated with the data found in the request body.
+      def update( params )
+        res = resource_for_path( params[:path] )
+        params[:body] = res.bind( res.service.load( params[:target], params[:principal] ), params[:body] ) if auto_bind == true
+        object = res.service.save_existing( params[:target], params[:body], params[:principal] )
+        render_model( params, object )
+      end
+      
+      # Tells whether the specified model will be rendered
+      # as a feed or entry. To be subclassed
+      def is_a_collection( model )
+        model == nil || model.is_a?( Array )
+      end
+      
+      # Implement me in subclasses
+      def is_a_service_doc( model )
+        
+      end
+      
+    end
+    
+    
+    # Specialization of a basic application, that provides support for 
+    # Sequel (http://sequel.rubyforge.org) configuration at startup by 
+    # implementing the 'init_database' method
+    class SequelApplication < RubyRest::Application
+      
+      # Specifies the list of resources to be persisted
+      def self.with_persistent_resources *resources
+        @persistent = resources
+      end
+      
+      # Returns the list of persistent resources
+      def self.persistent_resources
+        @persistent = [] if !@persistent
+        return @persistent
+      end
+      
+      # Connects all persistent resources to the database and optionnally
+      # recreates the database schema. For the moment this only 
+      # works with PostgreSQL databases
+      def init_database
+        @db = Sequel::Postgres::Database.new( @config )
+        self.class.persistent_resources.each{ |r| 
+          to_resource_class( r ).model.db=@db 
+        }
+        if @config[:destroy]
+          self.class.persistent_resources.each{ |r| 
+            to_resource_class( r ).model.recreate_table
+          }
+          puts "importing initial data..."
+          import_data 
+        end
+      end
+      
+      # PLease override this in subclasses
+      def import_data
+        
+      end
+      
+      # Tells whether the specified model will be rendered
+      # as a feed or entry. To be subclassed
+      def is_a_collection( model )
+        super( model ) || model.is_a?( Sequel::Dataset )
+      end
+      
+      def is_a_service_doc( model )
+        super( model ) || model.is_a?( RubyRest::Atom::ServiceDocument )
+      end
+      
+    end
+    
+end