nitro 0.10.0 → 0.11.0

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/rdoctask'
 require 'rake/testtask'
 require 'rake/gempackagetask'
 
-og = false 
+og = false
 
 task :default => :package
 
@@ -14,7 +14,7 @@ task :default => :package
 
 Rake::TestTask.new do |t|
 	t.libs << 'test'
-	t.test_files = FileList['test/**/tc*.rb'].exclude('**/tc*og*.rb')
+	t.test_files = FileList['test/**/tc*.rb'].exclude('**/tc*og*.rb').exclude('test/og/**/*')
 	t.verbose = true
 end
 
@@ -30,8 +30,8 @@ end
 
 Rake::RDocTask.new do |rd|
 	rd.main = 'README'
-	rd.rdoc_dir = 'rdoc'
-	rd.rdoc_files.include('README', 'INSTALL', 'lib/**/*.rb')
+	rd.rdoc_dir = 'doc/rdoc'
+	rd.rdoc_files.include('README', 'INSTALL', 'doc/og_config.txt', 'doc/og_tutorial.txt', 'lib/**/*.rb')
 	rd.options << '--all --inline-source'
 end
 
@@ -91,11 +91,11 @@ spec = Gem::Specification.new do |s|
 	s.summary = 'Nitro Web Engine'
 	s.description = 
 		'An efficient, multiparadigm and flexible platform for rapid ' +
-		'web application development. Implements a full development stack ' +
-		'(Model, View, Controller).'
-	
+		'web application development. Implements a full development stack.'
+
 	# s.add_dependency 'postgres-pr', '>= 0.3.0'
 	# s.add_dependency 'postgres', '>= 0.7.1'
+	# s.add_dependency 'ParseTree', '>= 1.3.3'
 	s.add_dependency 'extensions', '>= 0.5'
 	# s.add_dependency 'sqlite3-ruby', '>= 1.0.0'
 	# s.add_dependency 'mysql', '>= 2.5.1'

data/benchmark/og/bench.rb

@@ -1,12 +1,9 @@
 # * George Moschovitis  <gm@navel.gr>
 # (c) 2004-2005 Navel, all rights reserved.
-# $Id: bench.rb 255 2005-02-10 12:45:32Z gmosx $
+# $Id: bench.rb 263 2005-02-23 13:45:08Z gmosx $
 
-$:.unshift File.join(File.dirname(__FILE__), '..', '..', 'lib')
+require 'og'; include Og
 
-require 'og'
-
-GC.disable
 
 config = {
 	:adapter => 'sqlite',
@@ -28,8 +25,8 @@ class Article
 	end
 end
 
-Og::Database.drop_db!(config)
-db = Og::Database.new(config)
+Database.drop_db!(config)
+db = Database.new(config)
 
 # Benchmark the insert speed. Useful for finding
 # the improvement when using prepared statements.
@@ -44,6 +41,8 @@ sum = 0
 min = 999999
 max = -min
 
+GC.disable
+
 10.times do |i|
 
 	db.exec "DELETE FROM #{Article::DBTABLE}"
@@ -69,6 +68,8 @@ max = -min
 
 end
 
-puts "Min: #{min}"
-puts "Max: #{max}"
-puts "Average: #{sum/10}"
+puts %{
+Min: #{min}
+Max: #{max}
+Average: #{sum/10}
+}

data/doc/apache.txt

@@ -0,0 +1,9 @@
+= Apache
+
+Nitro runs under the Apache Web Server using FastCGI.
+
+== Setup
+
+Download and setup the latest Apache distribution:
+
+Download and setup the latest mod_fcgi distirbution:

data/doc/architecture.txt

@@ -1,28 +1,2 @@
+= Architecture
 
-
-
-Client: 
-Web Browsers, Mobile Phones, PDA, TV                  
-
-HttpServer: 
-handles .html, .gif/.jpg/.png, .css, .js, .swf, .ssi
-no loging, tuned for maximum performance, clustered
-
-AppServer: 
-handles dynamic pages, controller / actions (.sx, .si, .ss, .sc)
-loging, clustered
-
-Cluster:
-make distributed by hash! (all servers have access to all stateservers)
-and multiplex access.
-
-SyncServer:
-multiple servers for multiple services
-
-DBServer:
-Database
-Clustered (rdbms)
-
-DNSServer: 
-Provides dns services, initial clustering support.
-(inherently clustered)

data/doc/bugs.txt

@@ -1,7 +1,14 @@
+= Bugs
 
-IMPORTANT:
+=== Important
 
-SMALL:
+* multipart handling in fcgi adapter.
+
+=== Security
+
+* you can get the xthml files in the WEBrick adapter.
+
+=== Small
+
+* not correct content type in blog syndication.
 
-- the script filenames contain '//' path should not contain 
-  leading '/' ??

data/doc/config.txt

@@ -0,0 +1,22 @@
+= Configuration parameters
+
+This file presents a complete list of Nitro Configuration 
+Parameters.
+
+=== Session.store_type = :memory
+
+Selects the mechanism employed for storing the sessions.
+Available values are:
+
+[+:memory+]
+	This is the default mechanism, sessions are stored
+	in memory. Only useful in multithreaded environments
+	like WEBrick. 
+
+[+:drb+] 
+	Distributed Sessions using DRb. An independed DRb
+	server stores the sessions.
+
+In the future there will be more options available (:memcache,
+:filesys, :db)
+

data/doc/og_config.txt

@@ -0,0 +1,35 @@
+= Og Configuration parameters
+
+This file presents a complete list of Og configuration 
+parameters.
+
+=== Og.table_prefix = nil
+
+Attach the given prefix to all generated SQL table names.
+Usefull on hosting scenarios where you have to run multiple
+applications/sites on a single database.
+
+=== Og.auto_manage_classes = true
+
+If true, use Ruby's advanced introspection capabilities to 
+automatically manage classes that define properties.
+	
+=== Og.enchant_managed_classes = true
+
+If true, the library automatically 'enchants' managed classes.
+In enchant mode, special db aware methods are added to 
+managed classes and instances. If false, Og enchants only classes 
+that define properties.
+	
+=== Og.create_schema = true
+
+If set to true, Og attempts to recreate the database schema
+to store the managed objects. If the table for an object class
+exists, Og does not recreate it. It is useful to get Og to
+automatically create the schema for your application on setup,
+or when you add a new managed class to your application. On 
+the downside, it inflicts a longer startup time on the 
+application, so it is better to set this to false in 
+production / live environments.
+
+This option is by default true to facilitate easy development.

data/doc/og_tutorial.txt

@@ -0,0 +1,595 @@
+= Og Tutorial
+
+=== Introduction
+
+Ruby is a wonderful object oriented language featuring a well
+designed syntax and advanced constructs to bring the joy back
+to programming. Creating the object model to describe your
+problem domain is easy, but making this model persistent is
+another story: you have to deal with relational databases
+and the SQL language.
+
+RDBMS systems are a proven and robust technology for storing
+and querying data, but after experiencing the wonders of Ruby,
+it is hard not to wish for a better way to integrate the OOP
+and Relational paradigms.
+
+Og makes your dream come true! Og stands for ObjectGraph and
+provides a transparent way to make your objects persistent
+while leveraging the full querying power of an RDBMS system.
+In fact, Og is designed to use an RDBMS system like MySQL or
+PostgreSQL to implement the actual data store where the
+objects are serialized.
+
+But, enough with the techno-babble, let's walk through a simple
+example to give you a better idea of what Og can do.
+
+
+=== Installing Og
+
+The best way to install Og is through RubyGems. For example:
+
+gem install og
+
+In order to use Og with a specific RDBMS, you have to install
+the corresponding Ruby binding. A list of supported RDBMS's
+and information about the Ruby bindings can be found in the
+README file.
+
+Alternatively, you can install a .tar.gz or .zip distribution.
+You can find these at the following URL:
+
+http://www.rubyforge.com/projects/nitro
+
+
+=== A Basic Blog Model
+
+Blogs are in vogue. It seems that almost everyone is running a blog, and
+many try to code one from scratch. We'll review the steps necessary
+to generate the persistence model for a blog application using Og.
+
+Let's start by designing the objects we'll use. Our simple Blog
+will use these three objects:
+
+# Blog category
+
+class Category
+    attr_accessor :name
+end
+
+# Blog posting
+
+class Post
+    attr_accessor :title
+    attr_accessor :body
+    attr_accessor :author
+end
+
+# Blog comment
+
+class Comment
+    attr_accessor :title
+    attr_accessor :body
+    attr_accessor :author
+end
+
+As you can see, this is pure Ruby code. One of the features of
+Ruby is dynamic typing. When defining the attributes of our
+objects, we don't declare the actual type. However, in order to
+persist the model in SQL, we need to provide some hints to Og.
+
+Og provides a replacement to the attr* family of methods to
+facilitate attaching metadata to the object's attributes. An
+attribute that contains metadata is called a property. For
+each attr* method, there is a corresponding prop* method. That is,
+
+    attr          => prop
+    attr_accessor => prop_accessor
+    attr_reader   => prop_reader
+    attr_writer   => prop_writer
+
+Here are the class definitions using the property mechanism:
+
+require 'og'
+
+class Category
+    prop_accessor :name, String
+end
+
+class Post
+    prop_accessor :title, String
+    prop_accessor :body, String
+    prop_accessor :author, String
+    prop_accessor :create_time, Time
+    prop_accessor :hits, Fixnum
+end
+
+class Comment
+    prop_accessor :title, String
+    prop_accessor :body, String
+    prop_accessor :author, String
+    prop_accessor :create_time, Time
+end
+
+Notice that the prop_accessor works similar to Ruby's attr_accessor. 
+Here are some examples:
+
+prop :title, true, String
+prop_reader :title, :body, :author, String
+
+To make the definitions look even cleaner, Og provides the property alias:
+
+class Category
+    property :name, String
+end
+
+class Post
+    property :title, String
+    property :body, String
+    property :author, String
+    property :create_time, Time
+    property :hits, Fixnum
+end
+
+class Comment
+    property :title, String
+    property :body, String
+    property :author, String
+    property :create_time, Time
+end
+
+This is most of the information that Og needs to manage these objects. Before we continue,
+we need to setup the actual RDBMS data store used by Og. Currently, Og has built-in adapters
+for PostgreSQL, MySQL, SQLite3, and Oracle. For this example, we'll use the PostgreSQL adapter,
+so add this code after the class definitions.
+
+db = Og::Database.new(
+    :database => 'test',
+    :adapter  => 'psql',
+    :user     => 'postgres',
+    :password => 'navelrulez'
+)
+
+Now you are ready to save your first object into Postgres. Add the following code:
+
+# create the object
+p = Post.new
+p.title = 'Hello'
+p.body = 'World'
+p.author = 'tml'
+
+# save the object in the database
+p.save
+
+That's it! Og works behind the scenes doing all the work for you.
+This simple command, p.save, does the following:
+
+1. Creates the database 'test' if it doesn't exist.
+2. Creates a table to store Post objects if it doesn't exist.
+   The table's columns map to the object properties.
+3. Creates SQL indices.
+4. Creates any needed sequences.
+5. Serializes the object into the table.
+
+Issue the following SQL to see the result:
+
+SELECT * FROM og_post
+
+This is nice, but where does the #save method come from?
+Og uses Ruby's advanced introspection features to automatically
+'enchant' class that define properties. An enchanted class
+provides several methods that will be discussed in the following
+text. These enchanted classes are called *managed* classes.
+
+Before going on, let's look at another Og macro that eases object creation:
+
+p = Post.create
+
+Create automatically calls the save method. Here is another way to save the object:
+
+db << p
+
+OR
+
+db.save(p)
+
+
+Let's create a Category object.
+
+cat = Category.new
+cat.name = 'Programming'
+cat.save
+
+If you investigate the generated og_category table, you will
+see an 'oid' column which serves as the primary key. This
+column is added automatically by Og. You can use the oid
+values to lookup objects:
+
+cat = Category[1] # loads the category object with oid = 1
+
+OR
+
+cat = db.load(1, Category)
+
+As a convenience, Og allows you to lookup the category
+using the special property 'name':
+
+cat = Category['Programming']
+
+You can lookup objects by name only if the name property is
+defined.
+
+If you want to view Og's SQL, you can enable debug mode by setting this global 
+debug (DBG) variable:
+
+$DBG = true
+
+
+=== Customizing the Schema and Defining Relations
+
+Og makes our blog model persistent through a simple interface. The next step is to
+refine the schema and define relations between the objects:
+
+class Post; end
+class Comment; end
+
+class Category
+    property :name, String
+
+    many_to_many :posts, Post
+
+    def initialize(title = nil)
+        @title = title
+    end
+end
+
+class Post
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+    property :hits, Fixnum, :sql_index => true
+
+    has_many :comments, Comment
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+        @hits = 0
+    end
+end
+
+class Comment
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+
+    belongs_to :post, Post
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+Observe the :sql property option is used to refine
+the generated column type for the title property of Post,
+and how the :sql_index option is used to add an index to
+the generated table.
+
+Notice that the initialize methods provide default
+values to all parameters. This is required for all managed objects.
+
+Observe the many_to_many, has_many, and belongs_to macros.
+Og uses these macros to define the relations between
+standard Objects. In essence, Og defines a domain specific
+mini language. The following kinds of relations are
+supported:
+
+    * has_one: has one object of the given type.
+
+    * has_many: has many objects of the given type.
+
+    * belongs_to: belongs_to an object of the given type.
+
+    * many_to_many: defines a many-to-many relation. The corresponding
+      rows in the database are linked through a join table.
+
+    * refers_to: refers to another object.
+
+These macros generate the constructs needed to efficiently implement
+the corresponding relations. For example, the belongs_to macro generates
+the property that links to the parent. The many_to_many relation generates
+the join table that links the participating classes.
+
+Note that we have to use forward definitions of Post and Comment to satisfy
+Ruby's parser. Workarounds will be provided in a future version.
+
+After defining these relations, using and querying the object model is easy:
+
+cat = Category.create('Programming')
+
+cat.add_post { |p|
+     p.title = 'Title'
+     p.body = 'Body
+}
+
+cat.add_post { |p|
+    p.title = 'Another'
+    p.body = 'Hello'
+}
+
+cat.posts
+ => [Post(Title), Post(Another)]
+
+cat.posts[0].title
+ => Title
+
+cat.posts.size
+ => 2
+
+p = Post[1]
+p.title
+ => Title
+
+p.categories[0].title
+ => 'Programming'
+
+c = Comment.new('hello', 'world', 'tml')
+c.post = p
+c.save
+
+p.comments.size
+ => 1
+
+p.add_comment { |c|
+    c.title = 'Hi there'
+}
+
+p.comments[1].title
+  => 'Hi there'
+
+com = Comment.new('Hi there')
+p.add_comment(com)
+
+All the methods used in the above examples are generated automatically.
+These methods transparently modify the underlying SQL schema using efficient queries.
+
+Og provides full access to all features of the underlying RDBMS. Look at the following:
+
+post = Post.select("title='Title' and body='Body'")
+post.size
+ => 1
+post.hits
+ => 0
+
+Updating existing objects is easy too:
+
+p = Post[1]
+p.title = 'Changed'
+p.save
+
+p = Post[1]
+p.title
+ => 'Changed'
+
+You can also update specific properties, for example:
+
+p = Post[1]
+p.update_properties "body='Hello world'"
+
+p = Post[1]
+p.body
+ => 'Hello world'
+
+If you don't like a particular comment, you can easily delete it by doing the following:
+
+Comment.delete(comment)
+
+OR
+
+comment.delete!
+
+OR
+
+db.delete(comment)
+
+To delete all comments for a posting, enter the following:
+
+p.delete_all_comments
+
+When deleting an object that participates in relations, Og tries
+to delete all objects that belong to this object (ie, cascade deletes).
+
+All the generated methods take more parameters to customize their
+behaviour to suit your needs.
+
+
+=== Defining Callbacks
+
+Og provides a detailed callback facility allowing you to hook
+into a managed object's Lifecycle. This is a very useful
+feature that can improve your code considerably. To implement
+a callback, you have to define one or more of the following methods
+in your class:
+
+    * og_pre_insert
+    * og_post_insert
+    * og_pre_update
+    * og_post_update
+    * og_pre_insert_update
+    * og_post_insert_update
+    * self.og_pre_delete
+
+For example, the following code defines a callback for the Post class.
+
+class Post
+  ...
+
+  def og_post_insert(conn)
+        puts 'Hey, a new post was just posted!'
+    end
+end
+
+When post.save is called, you'll get this alert:
+
+p = Post.create('Hello')
+ => console: Hey, a new post was just posted!
+
+
+=== Using OOP techniques
+
+Og's managed objects are standard Ruby objects, so we can use class inheritance
+and module inclusion to minimize the code we have to write. Here's how we can
+improve the blog schema:
+
+class Category
+    property :name, String
+    many_to_many :posts, Post
+
+    def initialize(title = nil)
+        @title = title
+    end
+end
+
+class Common
+    property :title, String, :sql => 'VARCHAR2(32) NOT NULL'
+    property :body, String
+    property :author, String
+    property :create_time, Time
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+class Post < Common
+    property :hits, Fixnum, :sql_index => true
+    has_many :comments, Comment
+
+    def initialize(title = nil, body = nil, author = nil)
+        super
+        @hits = 0
+    end
+end
+
+class Comment < Common
+    belongs_to :post, Post
+end
+
+In essence, this feature allows you to create SQL tables using inheritance,
+saving you lots of time when using objects with similar properties. It's also
+less error prone.
+
+
+=== Defining Validation Rules
+
+When managing large amounts of data, enforcing data integrity is
+important. Og provides another domain specific mini language that allows
+you to define validation rules in a simple manner. In the following code,
+the blog schema is enriched with hints that allows Og to automatically generate
+validation code:
+
+class Common
+    property :title, String, :sql => 'NOT NULL VARCHAR(32)'
+    property :body, String
+    property :author, String
+    property :create_time, String
+
+    validate_value :title
+    validate_length :body, :range => 2..100, :msg_long => 'argh'
+    validate_format :author, :format => /[a-z]/, :msg => 'wrong format'
+
+    def initialize(title = nil, body = nil, author = nil)
+        @title, @body, @author = title, body, author
+        @create_time = Time.now
+    end
+end
+
+This code demonstrates some validations facilities. Using the validate_value
+macro, we enforce that the 'title' property will have a value. Using the
+validate_length macro, we enforce the minimum and maximum lengths for the
+'body' property. Using the validate_format macro, we enforce a required
+format for values assigned to the 'author' field.
+
+Let's see this validation in practice:
+
+c = Comment.new
+c.valid?
+ => false
+c.errors.count
+ => 3
+
+c.title = 'Hello'
+c.valid?
+c.errors.count
+ => 2
+
+The errors array contains a list of Error objects that point to the offending
+field and contain a descriptive message.
+
+With Og, you can customize almost everything! More information can be found in the source code
+(lib/glue/validation.rb). To whet your appetite, here is a list of predefined validation macros:
+
+    * validate_value
+    * validate_format
+    * validate_length
+    * validate_inclusion
+    * validate_confirmation
+
+
+=== TypeMacros
+
+If you look at the common class definition, you will notice that the :sql
+option looks kind of ugly:
+
+:sql => 'VARCHAR2(32) NOT NULL'
+
+When building larger object models, this issue comes up frequently. Og
+provides a elegant solution in the form of type macros:
+
+def VarChar(size)
+    return String, :sql => "VARCHAR2(#{size}) NOT NULL"
+end
+
+property :title, VarChar(30)
+
+
+=== Switching To Another Database
+
+While Postgres is a great database, let's assume that the client wants to switch to
+MySQL at the last minute. Don't worry, Og can easily accomodate this by simply changing
+the db reference in the configuration file to look like this and then re-running the example:
+
+db = Og::Database.new(
+    :database => 'test',
+    :adapter  => 'mysql',
+    :user     => 'postgres',
+    :password => 'navelrulez'
+)
+
+A new MySQL database is automatically created along with all tables, indices, etc. You get all 
+this with changing only one line of code!
+
+
+=== Is There More?
+
+You betcha! You can to find more about Og by reading the available RDoc documentation and browsing the examples.
+
+For any questions regarding Og, feel free to ask on the ruby-talk 
+mailing list (which is mirrored to comp.lang.ruby) or contact 
+mailto:gm@navel.gr.
+
+A Nitro specific mailing list is also available. You can post questions about
+Og to this list. Please subscribe to nitro-general@rubyforge.com. The homepage 
+for this list is available here:
+
+http://rubyforge.org/mailman/listinfo/nitro-general
+
+Note that Og is still under heavy development, so new features are being added frequently. 
+Be sure to check back for updates.
+
+
+