hanami-model 0.0.0 → 0.6.0

data/lib/hanami/model/adapters/abstract.rb

@@ -0,0 +1,281 @@
+require 'hanami/utils/basic_object'
+
+module Hanami
+  module Model
+    module Adapters
+      # It's raised when an adapter can't find the underlying database adapter.
+      #
+      # Example: When we try to use the SqlAdapter with a Postgres database
+      # but we didn't loaded the pg gem before.
+      #
+      # @see Hanami::Model::Adapters::SqlAdapter#initialize
+      #
+      # @since 0.1.0
+      class DatabaseAdapterNotFound < Hanami::Model::Error
+      end
+
+      # It's raised when an adapter does not support a feature.
+      #
+      # Example: When we try to get a connection string for the current database
+      # but the adapter has not implemented it.
+      #
+      # @see Hanami::Model::Adapters::Abstract#connection_string
+      #
+      # @since 0.3.0
+      class NotSupportedError < Hanami::Model::Error
+      end
+
+      # It's raised when an operation is requested to an adapter after it was
+      # disconnected.
+      #
+      # @since 0.5.0
+      class DisconnectedAdapterError < Hanami::Model::Error
+        def initialize
+          super "You have tried to perform an operation on a disconnected adapter"
+        end
+      end
+
+      # Represents a disconnected resource.
+      #
+      # When we use <tt>#disconnect</tt> for <tt>MemoryAdapter</tt> and
+      # </tt>FileSystemAdapter</tt>, we want to free underlying resources such
+      # as a mutex or a file descriptor.
+      #
+      # These adapters use to use anonymous descriptors that are destroyed by
+      # Ruby VM after each operation. Sometimes we need to clean the state and
+      # start fresh (eg. during a test suite or a deploy).
+      #
+      # Instead of assign <tt>nil</tt> to these instance variables, we assign this
+      # special type: <tt>DisconnectedResource</tt>.
+      #
+      # In case an operation is still performed after the adapter was disconnected,
+      # instead of see a generic <tt>NoMethodError</tt> for <tt>nil</tt>, a developer
+      # will face a specific message relative to the state of the adapter.
+      #
+      # @api private
+      # @since 0.5.0
+      #
+      # @see Hanami::Model::Adapters::Abstract#disconnect
+      # @see Hanami::Model::Adapters::MemoryAdapter#disconnect
+      # @see Hanami::Model::Adapters::FileSystemAdapter#disconnect
+      class DisconnectedResource < Utils::BasicObject
+        def method_missing(method_name, *)
+          ::Kernel.raise DisconnectedAdapterError.new
+        end
+      end
+
+      # Abstract adapter.
+      #
+      # An adapter is a concrete implementation that allows a repository to
+      # communicate with a single database.
+      #
+      # Hanami::Model is shipped with Memory and SQL adapters.
+      # Third part adapters MUST implement the interface defined here.
+      # For convenience they may inherit from this class.
+      #
+      # These are low level details, and shouldn't be used directly.
+      # Please use a repository for entities persistence.
+      #
+      # @since 0.1.0
+      class Abstract
+        # Initialize the adapter
+        #
+        # @param mapper [Hanami::Model::Mapper] the object that defines the
+        #   database to entities mapping
+        #
+        # @param uri [String] the optional connection string to the database
+        #
+        # @param options [Hash] a list of non-mandatory adapter options
+        #
+        # @since 0.1.0
+        def initialize(mapper, uri = nil, options = {})
+          @mapper = mapper
+          @uri    = uri
+          @options = options
+        end
+
+        # Creates or updates a record in the database for the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to persist
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def persist(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Creates a record in the database for the given entity.
+        # It should assign an id (identity) to the entity in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def create(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Updates a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def update(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Deletes a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [Object] the entity to delete
+        #
+        # @since 0.1.0
+        def delete(collection, entity)
+          raise NotImplementedError
+        end
+
+        # Returns all the records for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the records
+        #
+        # @since 0.1.0
+        def all(collection)
+          raise NotImplementedError
+        end
+
+        # Returns a unique record from the given collection, with the given
+        # identity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @since 0.1.0
+        def find(collection, id)
+          raise NotImplementedError
+        end
+
+        # Returns the first record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the first entity
+        #
+        # @since 0.1.0
+        def first(collection)
+          raise NotImplementedError
+        end
+
+        # Returns the last record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the last entity
+        #
+        # @since 0.1.0
+        def last(collection)
+          raise NotImplementedError
+        end
+
+        # Empties the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @since 0.1.0
+        def clear(collection)
+          raise NotImplementedError
+        end
+
+        # Executes a command for the given query.
+        #
+        # @param query [Object] the query object to act on.
+        #
+        # @since 0.1.0
+        def command(query)
+          raise NotImplementedError
+        end
+
+        # Returns a query
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param blk [Proc] a block of code to be executed in the context of
+        #   the query.
+        #
+        # @return [Object]
+        #
+        # @since 0.1.0
+        def query(collection, &blk)
+          raise NotImplementedError
+        end
+
+        # Wraps the given block in a transaction.
+        #
+        # For performance reasons the block isn't in the signature of the method,
+        # but it's yielded at the lower level.
+        #
+        # Please note that it's only supported by some databases.
+        # For this reason, the options may vary from adapter to adapter.
+        #
+        # @param options [Hash] options for transaction
+        #
+        # @see Hanami::Model::Adapters::SqlAdapter#transaction
+        # @see Hanami::Model::Adapters::MemoryAdapter#transaction
+        #
+        # @since 0.2.3
+        def transaction(options = {})
+          raise NotImplementedError
+        end
+
+        # Returns a string which can be executed to start a console suitable
+        # for the configured database.
+        #
+        # @return [String] to be executed to start a database console
+        #
+        # @since 0.3.0
+        def connection_string
+          raise NotSupportedError
+        end
+
+        # Executes a raw command
+        #
+        # @param raw [String] the raw statement to execute on the connection
+        #
+        # @return [NilClass]
+        #
+        # @since 0.3.1
+        def execute(raw)
+          raise NotImplementedError
+        end
+
+        # Fetches raw records from
+        #
+        # @param raw [String] the raw query
+        # @param blk [Proc] an optional block that is yielded for each record
+        #
+        # @return [Enumerable<Hash>, Array<Hash>]
+        #
+        # @since 0.5.0
+        def fetch(raw, &blk)
+          raise NotImplementedError
+        end
+
+        # Disconnects the connection by freeing low level resources
+        #
+        # @since 0.5.0
+        def disconnect
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/hanami/model/adapters/file_system_adapter.rb

@@ -0,0 +1,288 @@
+require 'thread'
+require 'pathname'
+require 'hanami/model/adapters/memory_adapter'
+
+module Hanami
+  module Model
+    module Adapters
+      # In memory adapter with file system persistence.
+      # It behaves like the SQL adapter, but it doesn't support all the SQL
+      # features offered by that kind of databases.
+      #
+      # This adapter SHOULD be used only for development or testing purposes.
+      # Each read/write operation is wrapped by a `Mutex` and persisted to the
+      # disk.
+      #
+      # For those reasons it's really unefficient, but great for quick
+      # prototyping as it's schema-less.
+      #
+      # It works exactly like the `MemoryAdapter`, with the only difference
+      # that it persist data to the disk.
+      #
+      # The persistence policy uses Ruby `Marshal` `dump` and `load` operations.
+      # Please be aware of the limitations this model.
+      #
+      # @see Hanami::Model::Adapters::Implementation
+      # @see Hanami::Model::Adapters::MemoryAdapter
+      # @see http://www.ruby-doc.org/core/Marshal.html
+      #
+      # @api private
+      # @since 0.2.0
+      class FileSystemAdapter < MemoryAdapter
+        # Default writing mode
+        #
+        # Binary, write only, create file if missing or erase if don't.
+        #
+        # @see http://ruby-doc.org/core/File/Constants.html
+        #
+        # @since 0.2.0
+        # @api private
+        WRITING_MODE = File::WRONLY|File::BINARY|File::CREAT
+
+        # Default chmod
+        #
+        # @see http://en.wikipedia.org/wiki/Chmod
+        #
+        # @since 0.2.0
+        # @api private
+        CHMOD        = 0644
+
+        # File scheme
+        #
+        # @see https://tools.ietf.org/html/rfc3986
+        #
+        # @since 0.2.0
+        # @api private
+        FILE_SCHEME  = 'file:///'.freeze
+
+        # Initialize the adapter.
+        #
+        # @param mapper [Object] the database mapper
+        # @param uri [String] the connection uri
+        # @param options [Hash] a hash of non-mandatory adapter options
+        #
+        # @return [Hanami::Model::Adapters::FileSystemAdapter]
+        #
+        # @see Hanami::Model::Mapper
+        #
+        # @api private
+        # @since 0.2.0
+        def initialize(mapper, uri, options = {})
+          super
+          prepare(uri)
+
+          @_mutex = Mutex.new
+        end
+
+        # Returns all the records for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the records
+        #
+        # @api private
+        # @since 0.2.0
+        def all(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns a unique record from the given collection, with the given
+        # id.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def find(collection, id)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns the first record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the first entity
+        #
+        # @api private
+        # @since 0.2.0
+        def first(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns the last record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the last entity
+        #
+        # @api private
+        # @since 0.2.0
+        def last(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Creates a record in the database for the given entity.
+        # It assigns the `id` attribute, in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id=] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def create(collection, entity)
+          _synchronize do
+            super.tap { write(collection) }
+          end
+        end
+
+        # Updates a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def update(collection, entity)
+          _synchronize do
+            super.tap { write(collection) }
+          end
+        end
+
+        # Deletes a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to delete
+        #
+        # @api private
+        # @since 0.2.0
+        def delete(collection, entity)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Deletes all the records from the given collection and resets the
+        # identity counter.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @api private
+        # @since 0.2.0
+        def clear(collection)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Fabricates a query
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param blk [Proc] a block of code to be executed in the context of
+        #   the query.
+        #
+        # @return [Hanami::Model::Adapters::Memory::Query]
+        #
+        # @see Hanami::Model::Adapters::Memory::Query
+        #
+        # @api private
+        # @since 0.2.0
+        def query(collection, context = nil, &blk)
+          # _synchronize do
+            read(collection)
+            super
+          # end
+        end
+
+        # Database informations
+        #
+        # @return [Hash] per collection informations
+        #
+        # @api private
+        # @since 0.2.0
+        def info
+          @collections.each_with_object({}) do |(collection,_), result|
+            result[collection] = query(collection).count
+          end
+        end
+
+        # @api private
+        # @since 0.5.0
+        #
+        # @see Hanami::Model::Adapters::Abstract#disconnect
+        def disconnect
+          super
+
+          @_mutex = DisconnectedResource.new
+          @root   = DisconnectedResource.new
+        end
+
+        private
+        # @api private
+        # @since 0.2.0
+        def prepare(uri)
+          @root = Pathname.new(uri.sub(FILE_SCHEME, ''))
+          @root.mkpath
+
+          # Eager load previously persisted data.
+          @root.each_child do |collection|
+            collection = collection.basename.to_s.to_sym
+            read(collection)
+          end
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _synchronize
+          @_mutex.synchronize { yield }
+        end
+
+        # @api private
+        # @since 0.2.0
+        def write(collection)
+          path = @root.join("#{ collection }")
+          path.open(WRITING_MODE, CHMOD) {|f| f.write _dump( @collections.fetch(collection) ) }
+        end
+
+        # @api private
+        # @since 0.2.0
+        def read(collection)
+          path = @root.join("#{ collection }")
+          @collections[collection] = _load(path.read) if path.exist?
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _dump(contents)
+          Marshal.dump(contents)
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _load(contents)
+          Marshal.load(contents)
+        end
+      end
+    end
+  end
+end