== Welcome to Neo4j.rb

Neo4j.rb is a graph database for JRuby.

You can think of \Neo4j as a high-performance graph engine with all the features of a mature and robust database.
The programmer works with an object-oriented, flexible network structure rather than with strict and static tables — yet enjoys all the benefits of a fully transactional, enterprise-strength database.

It uses two powerful and mature Java libraries:
* {Neo4J}[http://www.neo4j.org] - for persistence and traversal of the graph
* {Lucene}[http://lucene.apache.org/java/docs/index.html] for querying and indexing.

=== Documentation

* {Guides and API}[http://neo4j.rubyforge.org/guides/index.html]
* {Blog: Neo4j and Rails 3}[http://blog.jayway.com/2011/03/02/neo4j-rb-1-0-0-and-rails-3/]

=== Why Neo4j.rb or a Graph Database ?

Here are some of the major benefits of Neo4j.rb

* Domain Modeling - use the language of a graph (nodes/relationship/properties) to express your domain !
  * Schema Less and Efficient storage of Semi Structured Information
  * No {O/R mismatch}[http://en.wikipedia.org/wiki/Object-relational_impedance_mismatch] - very natural to map a graph to an \Object Oriented language like Ruby.
* {Performance}[http://www.oscon.com/oscon2009/public/schedule/detail/8364]
* Embedded Database - no database tier, easier to install, test, deploy and configure. It is run in the same process as your application.
* Express Queries as Traversals
  * Fast deep traversal instead of slow SQL queries that span many table joins.
  * Very natural to express graph related problem with traversals (recommendation engine, find shortest parth etc..)
* Seamless integration with Ruby on \Rails.
* ACID Transaction with rollbacks support.


=== Some Examples

==== Neo4j::Node

Example of creating a Neo4j::Node

  require "rubygems"
  require 'neo4j'

  Neo4j::Transaction.run do
    node = Neo4j::Node.new (:name => 'andreas')
    node.outgoing(:friends) << Neo4j::Node.new (:name => 'peter')
    node.outgoing(:friends).each {|node| puts "name #{node[:name]}"}
  end

==== Neo4j::Mapping::NodeMixin

Example of mapping a ruby class to a node and delaring properties and relationships and lucene index.

  class Person
    include Neo4j::NodeMixin
    property :name
    property :city

    has_n :friends
    has_one :address
    index :name
  end

  # assume we have an transaction already running
  andreas = Person.new (:name => 'andreas')
  andreas.friends << Person.new (:name => 'peter')
  andreas.friends.each {|person| puts "name #{person.name}" }
  Person.find("name: andreas").first.name # => 'andreas'

==== Neo4j::Rails::Model

Example of using Neo4j with Rails 3 (ActiveModel)

  class User < Neo4j::Model
    attr_accessor :password
    attr_accessible :email, :password, :password_confirmation, :pending_account

    after_save   :encrypt_password

    email_regex = /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i

    property :email
    index :email

    has_one(:avatar).to(Avator)

    validates :email, :presence => true,:format   => { :with => email_regex }
    validates :email, :uniqueness => true, :unless => :pending_account?
    accepts_nested_attributes_for :avatar, :allow_destroy => true

    ...
  end

==== Generate a Rails Application

Example of creating an Neo4j Application from scratch:

 gem install rails
 rails new myapp -m http://andreasronge.github.com/rails3.rb
 cd myapp
 bundle
 rails generate scaffold User name:string email:string
 rails s
 open a webbrowser: http://localhost:3000/users

To run it with Tomcat instead of WEBrick
  
  gem install trinidad
  trinidad


=== Presentation Materials and other URLs
* {Intoduction to Neo4j.rb}[http://www.slideshare.net/andreasronge/neo4jrb]
* {Nordic Ruby 2010 May 21-23}[http://nordicruby.org/speakers#user_29]
* {Neo4j wiki, check the guidelines and domain modeling gallery pages}[http://wiki.neo4j.org/content/Main_Page]

=== Project information
* {GitHub}[http://github.com/andreasronge/neo4j/tree/master]
* {Lighthouse Issue Tracking}[http://neo4j.lighthouseapp.com]
* {Twitter}[http://twitter.com/ronge]
* IRC -  #neo4j @ irc.freenode.net
* {Mailing list, neo4jrb@googlegroups.com}[http://groups.google.com/group/neo4jrb]

=== Contributing

Have you found a bug, need help or have a patch ?
Just clone neo4j.rb and send me a pull request or email me.
Do you need help - send me an email (andreas.ronge at gmail dot com).
Please also check/add issues at lighthouse, http://neo4j.lighthouseapp.com

=== License
* Neo4j.rb - MIT, see the LICENSE file http://github.com/andreasronge/neo4j/tree/master/LICENSE.
* Lucene -  Apache, see http://lucene.apache.org/java/docs/features.html
* \Neo4j - Dual free software/commercial license, see http://neo4j.org/