orient_db_client 0.0.2 → 0.0.3

data/README.md

@@ -14,52 +14,142 @@ Supported OrientDB Releases
 I've tested this against OrientDB-1.0rc9 which is the current official release as of writing this README.
 
 
+Supported Ruby Versions
+---------------------------
+
+This gem has only been tested on 1.9.3.  It *should* run on any 1.9 install, and will definitely NOT run on 1.8 due to the use of Encoding.  Compatibility with 1.8 is planned, but not scheduled for any particular milestone yet.
+
+
 Basic Usage
 -----------
 
+There are two classifications of interaction with the OrientDB server:  Server and Database.  
+
+A server session is used for creating and deleting databases, as well as confirming their existence.  (Setting and reading the server configuration is also part of the protocol, but not yet supported by this gem.)
+
+A database session is used to performed all other work on a database, including but not limited to record CRUD operations, querying, and managing clusters (which are the physical files and logical subdivisions of an OrientDB database, not to be confused with clustering in the networking sense.)
+
+## Connecting to an OrientDB Server
+
+Before obtaining server or database sessions, a connection must be made to an OrientDB server instance.  There isn't much to this part.
+
+    require 'orient_db_client'
+
+    connection = OrientDBClient.connect('localhost')
+
+If you need to specify the port, pass it in the options Hash:
+
+    connection = OrientDBClient.connect('localhost', :port => 2424)
+
+When you're done with the connection (and all of the sessions you have opened within it):
+
+    connection.close
 
 ## Server Operations
 
-    require 'orient_db_client`
+A server session is only needed when an application wants to create, delete, or confirm the existence of a database.
 
-    connection = OrientDbClient.connect('0.0.0.0', { :port => 2424 })
+To obtain a server session, call #open_server on the connection.  This requires user credentials from the `<users>` section of the OrientDB server's `orientdb-server-config.xml` file.
 
     server = connection.open_server({
         :user => 'root',
         :password => '<password>'
     })
 
+**NOTE:** *I strongly suggest figuring out OrientDB's permission system and creating a non-root user in Orient's config.xml. :)*
+
+Create a database using local storage (support for in-memory databases forthcoming):
+
     server.create_local_database("my_database")
 
-    server.delete_database(database_name)
+Confirm that a database exists:
 
+    server.database_exists? "my_database"
+
+Delete a database:
+
+    server.delete_database(my_database)
 
-## Database Operations
 
-    require 'orient_db_client`
+## Database Operations
 
-    connection = OrientDbClient.connect('0.0.0.0', { :port => 2424 })
+Most work in OrientDB will be done with database sessions.  To open one:
 
     database = connection.open_database(database_name, {
         :user => 'admin',
         :password => 'admin'
     })
 
-    cluster_id = database.create_physical_cluster("test")
+**NOTE:** *By default, OrientDB databases have three users pre-created, `reader`, `writer`, and `admin`.  Their passwords are the same as their names.  Don't forget to change these before running your OrientDB server in production. :)*
+
+
+### CRUD
+
+By default, a database contains the following clusters:  internal, index, default, orids, orole, and ouser.  (I'm not entirely sure what that default cluster is for, so I don't write to it.  It may be an all-purpose starter cluster though.)
+
+Before records can be stored in the database, a cluster must be created to contain them.  Create one like this:
+
+    cluster_id = database.create_physical_cluster("mycluster")
 
-    record = { :document => { 'key1' => 'value1' } }
+This adds a physical (file) cluster to the database.  (Support for logical clusters forthcoming.)
+
+This gem was written to be somewhat liberal with what it will accept as a valid record Hash.  The gem will make implicit decisions about how to serialize each of the values.
+
+The following is an acceptable record:
+
+    record = { :key1 => 'value1', 'key2' => 2, 'key3' => 3.45 }
+
+The symbolic `:key1` will be converted into a string.  Key2's value will be stored as an integer.  Key3's value will be stored as a double.
+
+To gain more explicit control over serialization, a record must conform to the following structure:
+
+    record = { :document => { :key1 => 'value1', 'key2' => 2, 'key3' => 3.45 },
+               :structure => { 'key1' => :string, 'key2' => :integer, 'key3' => :double },
+               :class => "MyClass" }
+
+**NOTE:** The `:class` is optional.  It is only useful in databases that use classes to implement a schema.
+
+Creating a record is straightforward:
 
     rid = database.create_record(cluster_id, record)
 
+The return value is an OrientDbClient::Rid.  You can get the native "#i:p" form by calling #to_s on the returned Rid.
+
+An existing record can be read using #load_Record:
+
     loaded_record = database.load_record(rid)
-    loaded_record[:document]['key1'] = 'updated'
 
+Records returned by #load_record will contain the above `:document` and `:structure` keys, along with `:record_version`, `:cluster_id`, and `:cluster_position`.  `:class` will be provided if the record has a class.
+
+To update the record:
+
+    loaded_record[:document]['key1'] = 'updated'
     version = database.update_record(loaded_record, rid, :incremental)
 
-    edited_record = database.load_record(rid)
+The updated record is stored to the database, and its new version number is returned.  The `:incremental` option tells OrientDB to increment the record's version number when persisting the record.  Alternatively, `:none` can be passed and OrientDB will not perform any type of versioning.  Lastly, an explicit numeric version can be passed and it will be used as the record's new version number.
+
+**NOTE:** OrientDB does not currently retain old records.  It isn't so much "version control" as version marking.
+
+
+To delete a record:
+
+    database.delete_record(rid, version)
+
+The version must match the version number of the record as it is currently stored in the database.
+
+
+### Querying (Experimental)
+
+OrientDB implements a SQL-like language that can be used to query records, add/alter/remove clusters, add/alter/remove classes, and more.  See the [SQL section](http://code.google.com/p/orient/wiki/SQL) of OrientDB's Wiki for more information.
+
+
+Use the #query method to send a query.  **Be careful with this method.**  Parameterized queries and sanitization have not been implemented in the gem.  Insufficient sanitization of SQL strings sent to this method could open up the database to SQL Injection attacks.  While OrientDB's SQL language is still evolving, it will be difficult to know what kind of vulnerabilities exist.
+
+    database.query "SELECT FROM cluster:mycluster"
 
-    database.delete_record(rid, edited_record[:record_version])
+This should return an array of deserialized records.
 
+**NOTE: Expect this to be buggy right now.**  *OrientDB's protocol mentions several possible return values from a query, but I've only been able to get it to return record collections in practice.  As such, I've not coded for the possibility of getting back a single record, getting back raw data, or getting back a flat response.  I'm not even sure what the latter two look like when they come out of the OrientDB server.*
 
 Testing
 -------

data/lib/orient_db_client/protocols/protocol7.rb

@@ -212,18 +212,15 @@ module OrientDbClient
 			end
 
 			def self.db_create(socket, session, database, options = {})
-                if options.is_a?(String)
-                    options = { :storage_type => options }
-                end
+        if options.is_a?(String) || options.is_a?(Symbol)
+            options = { :storage_type => options }
+        end
 
-                options = { :storage_type => 'local' }.merge(options)
+        options = { :storage_type => 'local' }.merge(options)
 
-				socket.write NetworkMessage.new { |m|
-					m.add :byte,	Operations::DB_CREATE
-					m.add :integer, session
-					m.add :string,	database
-					m.add :string,	options[:storage_type]
-				}.pack
+        options[:storage_type] = options[:storage_type].to_s
+
+				socket.write make_db_create_message(session, database, options).pack
 
 				read_response(socket)
 
@@ -385,6 +382,19 @@ module OrientDbClient
 
 			private
 
+			def self.make_db_create_message(*args)
+				session = args.shift
+				database = args.shift
+				options = args.shift
+
+				NetworkMessage.new { |m|
+					m.add :byte,		Operations::DB_CREATE
+					m.add :integer, session
+					m.add :string,	database
+					m.add :string,	options[:storage_type].to_s
+				}
+			end
+
 			def self.read_byte(socket)
 				socket.read(1).unpack('C').first
 			end

data/lib/orient_db_client/protocols/protocol9.rb

@@ -31,21 +31,10 @@ module OrientDbClient
                 end
 
                 options = {
-                    :database_type => 'document',
-                    :storage_type => 'local'
+                    :database_type => 'document'
                 }.merge(options)
 
-                socket.write NetworkMessage.new { |m|
-                    m.add :byte,    Operations::DB_CREATE
-                    m.add :integer, session
-                    m.add :string,  database
-                    m.add :string,  options[:database_type]
-                    m.add :string,  options[:storage_type]
-                }.pack
-
-                read_response(socket)
-
-                { :session => read_integer(socket) }
+                super
             end
 
             def self.db_open(socket, database, options = {})
@@ -83,6 +72,23 @@ module OrientDbClient
                 { :session          => read_integer(socket),
                   :message_content  => read_record_load(socket) }
             end
+
+            private
+
+            def self.make_db_create_message(*args)
+                session = args.shift
+                database = args.shift
+                options = args.shift
+
+                NetworkMessage.new { |m|
+                    m.add :byte,    Operations::DB_CREATE
+                    m.add :integer, session
+                    m.add :string,  database
+                    m.add :string,  options[:database_type].to_s
+                    m.add :string,  options[:storage_type].to_s
+                }
+            end
+
         end
     end
 end

data/lib/orient_db_client/serializers/serializer7.rb

@@ -35,7 +35,8 @@ module OrientDbClient
                 end
 
                 document.each do |k, v|
-                    result << "#{k}:#{serialize_item(v, structure[k])}"
+                    key_struct = structure[k.to_s] || structure[k.to_sym]
+                    result << "#{k}:#{serialize_item(v, key_struct)}"
                 end
 
                 serialized_document = "#{recordClass}#{result.join(",")}"
@@ -109,6 +110,8 @@ module OrientDbClient
                     serialize_double(value)
                 when :float
                     serialize_float(value)
+                when :integer
+                    serialize_integer(value)
                 when :long
                     serialize_long(value)
                 when :map

data/lib/orient_db_client/server_session.rb

@@ -3,7 +3,15 @@ require 'orient_db_client/session'
 module OrientDbClient
 	class ServerSession < Session
 		def create_local_database(database, options = {})
-			@connection.create_database(@id, database)
+			options[:storage_type] = :local
+
+			@connection.create_database(@id, database, options)
+		end
+
+		def create_memory_database(database, options = {})
+			options[:storage_type] = :memory
+
+			@connection.create_database(@id, database, options)
 		end
 
 		def database_exists?(database)

data/lib/orient_db_client/version.rb

@@ -1,3 +1,3 @@
 module OrientDbClient
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/integration/server_session_test.rb

@@ -34,4 +34,19 @@ class TestServerSession < MiniTest::Unit::TestCase
   		@session.delete_database(database) if @session.database_exists?(database)
   	end
   end
+
+  def test_create_and_delete_memory_database_commands
+    skip # Bug in OrientDB-1.0rc9 prevents this test from passing
+
+    database = "test_create_memory_database"
+
+    @session.delete_database(database) if @session.database_exists?(database)
+
+    begin
+      @session.create_memory_database(database)
+      assert @session.database_exists?(database)
+    ensure
+      @session.delete_database(database) if @session.database_exists?(database)
+    end
+  end
 end

data/test/unit/serializers/serializer7_test.rb

@@ -9,7 +9,7 @@ class TestSerializer7 < MiniTest::Unit::TestCase
         record = {
             :class => 'OClass',
             :structure => {
-                'buffer'                => :binary,
+                :buffer                 => :binary,
                 'true'                  => :boolean,
                 'false'                 => :boolean,
                 'byte'                  => :byte,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: orient_db_client
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-05 00:00:00.000000000 Z
+date: 2012-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -123,12 +123,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2784375670515319189
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 2784375670515319189
 requirements: []
 rubyforge_project: orient_db_client
 rubygems_version: 1.8.21