spiderfw 0.6.23 → 0.6.24

data/lib/spiderfw/model/request.rb

@@ -6,13 +6,16 @@ module Spider; module Model
     # the SELECT ... part of an SQL query.
     
     class Request < ModelHash
-        # (bool) if true, the total number of rows returned by the query is requested.
+        # @return [bool] if true, the total number of rows returned by the query is requested.
         attr_accessor :total_rows
-        # (array) find also the given subclasses of the queried model.
+        # @return [bool] find also the given subclasses of the queried model.
         attr_reader :polymorphs
-        # (bool) if true, the request will be expanded with lazy groups on load
+        # @return [bool] if true, the request will be expanded with lazy groups on load
         attr_accessor :expandable
         
+        # @param [Array|Hash] value Value to initialize the Request with. May be a Hash, or an Array of elements.
+        # @param [Hash] params Params may have:
+        #                      * :total_rows  Request the total rows corresponding to the Query from the storage
         def initialize(val=nil, params={})
             if (val.is_a?(Array))
                 super()
@@ -25,13 +28,18 @@ module Spider; module Model
             @expandable = true
         end
 
+        # Initializes a Request that should not be expanded by the Mapper
+        # @param [Array|Hash] val
+        # @param [Hash] params
+        # @return [Request]
         def self.strict(val=nil, params={})
             r = self.new(val, params)
             r.expandable = false
             r
         end
         
-        # TODO: fix/remove?
+        # @param [Element|String|Symbol] Element to request
+        # @return [void]
         def request(element) # :nodoc:
             if element.is_a?(Element)
                 self[element.name.to_s] = true
@@ -43,48 +51,47 @@ module Spider; module Model
                 self[element] = true
             end
         end
-    
-        # Requests all base types
-        def load_all_simple
-            @load_all_simple = true
-        end
-        
-        def load_all_simple?
-            @load_all_simple
-        end
         
-        # Adds a request for a subclass.
+        # Requests that the mapper looks for subclasses of the given type, loading
+        # additional subclass specific elements specified in the request
+        # @param [Class<BaseModel] type The subclass
+        # @param [Request] request Request for subclass specific elements
         def with_polymorphs(type, request)
             @polymorphs[type] = request
         end
         
+        # @return [bool] True if there are requested polymorphs
         def polymorphs?
             @polymorphs.empty? ? false : true
         end
         
-        # Requests only subclasses, not the queried model.
+        # Requests that only the subclasses requested with {#with_polymorphs} are returned,
+        # not the mapper's base class
+        # @return [self]
         def only_polymorphs
             @only_polymorphs = true
             return self
         end
-        
+
+        # @return [bool] True if only polymorphs should be returned
         def only_polymorphs?
             @only_polymorphs
         end
         
+        # Requests that the mapper retrieves also objects belonging to the model's superclass
+        # @return [self] 
         def with_superclass
             @with_superclass = true
             return self
         end
         
-        def with_superclass=(val)
-            @with_superclass = val
-        end
-        
+        # @return [bool] true if the superclass was requested with {#with_superclass}
         def with_superclass?
             @with_superclass
         end
-        
+
+
+        # @return [bool] true if the Request can be expanded by the mapper (using lazy groups)
         def expandable?
             @expandable
         end

data/lib/spiderfw/model/storage/base_storage.rb

@@ -2,6 +2,9 @@ require 'spiderfw/model/storage/connection_pool'
 
 module Spider; module Model; module Storage
     
+    # @abstract
+    # This class is subclassed by classes that interact with different storage backends.
+    # See also {Db::DbStorage}, {Document::DocumentStorage}.
     class BaseStorage
         include Spider::Logger
         attr_reader :url
@@ -15,38 +18,48 @@ module Spider; module Model; module Storage
             # An Hash of storage capabilities. The default for db storages is 
             # {:autoincrement => false, :sequences => true, :transactions => true}
             # (The BaseStorage class provides file sequences in case the subclass does not support them.)
+            # @return [Hash]
             attr_reader :capabilities
             
+            # @return [Symbol] A label for the storage's class.            
             def storage_type
                 :none
             end
             
+            # @return [Sync] A Sync object to use for sequences
             def sequence_sync
                 @sequence_sync ||= ::Sync.new
             end
 
+            # @return [Array] Base types supported by the backend.
             def base_types
                 Model.base_types
             end
             
-            # True if given named capability is supported by the Storage.
+            # @return [bool] True if given named capability is supported by the backend.
             def supports?(capability)
                 @capabilities[capability]
             end
             
-            # Returns a new connection. Must be implemented by the subclasses; args are implementation specific.
+            # @abstract
+            # @return [Object] Returns a new connection. Must be implemented by the subclasses; args are implementation specific.
             def new_connection(*args)
                 raise "Unimplemented"
             end
 
+            # @abstract
+            # @return [Fixnum|nil] Maximum number of connections possible for this backend (or nil if unlimited)
             def max_connections
                 nil
             end
 
+            # @return [Hash] An Hash of connection pools for each backend.
             def connection_pools
                 @pools ||= {}
             end
 
+            # @param [*args] Storage specific arguments
+            # @return [Object] Retrieves a native connection to the backend from the {ConnectionPool}.
             def get_connection(*args)
                 @pools ||= {}
                 @pools[args] ||= ConnectionPool.new(args, self)
@@ -54,6 +67,9 @@ module Spider; module Model; module Storage
             end
 
             # Frees a connection, relasing it to the pool
+            # @param [Object] conn The connection
+            # @param [Array] conn_params An array of connection params that were used to create the connection.
+            # @return [void]
             def release_connection(conn, conn_params)
                 return unless conn
                 return unless @pools && @pools[conn_params]
@@ -61,50 +77,77 @@ module Spider; module Model; module Storage
             end
 
             # Removes a connection from the pool.
+            # @param [Object] conn The connection
+            # @param [Array] conn_params An array of connection params that were used to create the connection.
+            # @return [void]
             def remove_connection(conn, conn_params)
                 return unless conn
                 return unless @pools && @pools[conn_params]
                 @pools[conn_params].remove(conn)
             end
 
+            # @abstract
+            # Closes the native connection to the backend.
+            # @param [Object] conn The native connection
+            # @return [void]
             def disconnect(conn)
                 raise "Virtual"
             end
 
+            # @abstract
             # Checks whether a connection is still alive. Must be implemented by subclasses.
+            # @param [Object] conn The native connection
+            # @return [void]
             def connection_alive?(conn)
                 raise "Virtual"
             end
 
+            # Copies capabilities on subclasses
+            # @param [Class<BaseStorage] subclass
+            # @return [void]
             def inherited(subclass)
                 subclass.instance_variable_set("@capabilities", @capabilities)
             end
             
         end
         
-        
+        # Creates a new storage instance.
+        # @param [String] url The backend-specific url for the connection
         def initialize(url)
             @url = url
             @configuration = {}
             parse_url(url)
         end
         
+        # Sets configuration for the Storage
+        # @param [Hash] conf The configuration
+        # @return [void]
         def configure(conf)
             @configuration.merge!(conf.to_hash)
         end
         
+        # @abstract
+        # Splits a backend-specific connection url into parts
+        # @param [String] url
+        # @return [Array]
         def parse_url(url)
             raise StorageException, "Unimplemented"
         end
         
+        # @abstact
+        # @param [Class<BaseModel]
+        # @return [Mapper] Returns the instance of a mapper for the storage and the given model
         def get_mapper(model)
             raise StorageException, "Unimplemented"
         end
         
+        # @param [Symbol] capability
+        # @return [bool] True if the backend supports the given capability
         def supports?(capability)
             self.class.supports?(capability)
         end
         
+        # @return [Hash] An hash of thread-local values for this connection
         def curr
             var = nil
             if Spider.conf.get('storage.shared_connection')
@@ -120,17 +163,19 @@ module Spider; module Model; module Storage
             }
         end
         
+        # @return [ConnectionPool|nil] The ConnectionPool managing the current connection params
         def connection_pool
             self.class.connection_pools[@connection_params]
         end
         
         # Instantiates a new connection with current connection params.
+        # @return [void]
         def connect
             return self.class.get_connection(*@connection_params)
             #Spider::Logger.debug("#{self.class.name} in thread #{Thread.current} acquired connection #{@conn}")
         end
         
-        # True if currently connected.
+        # @return [bool] True if currently connected.
         def connected?
             curr[:conn] != nil
         end
@@ -138,6 +183,8 @@ module Spider; module Model; module Storage
         
         # Returns the current connection, or creates a new one.
         # If a block is given, will release the connection after yielding.
+        # @yield [Object] If a block is given, it is passed the connection, which is released after the block ends.
+        # @return [Object] The connection
         def connection
             curr[:conn] = connect
             if block_given?
@@ -149,15 +196,18 @@ module Spider; module Model; module Storage
             end
         end
         
+        # @return [Hash] current connection attributes
         def self.connection_attributes
             @connection_attributes ||= {}
         end
         
+        # @return [Hash] current connection attributes
         def connection_attributes
             self.class.connection_attributes[connection] ||= {}
         end
         
         # Releases the current connection to the pool.
+        # @return [void]
         def release
             # The subclass should check if the connection is alive, and if it is not call remove_connection instead
             c = curr[:conn]
@@ -169,40 +219,59 @@ module Spider; module Model; module Storage
             #@conn = nil
         end
         
-        # Prepares a value for saving.
+        # Prepares a value which will be saved into the backend.
+        # @param [Class] type
+        # @param [Object] value 
+        # @param [Symbol] save_mode :insert or :update or generic :save
+        # @return [Object] The prepared value
         def value_for_save(type, value, save_mode)
             return prepare_value(type, value)
         end
         
-        # Prepares a value that will be used in a condition.
+        # Prepares a value that will be used in a condition on the backend.
+        # @param [Class] type
+        # @param [Object] value
+        # @return [Object] The prepared value
         def value_for_condition(type, value)
             return prepare_value(type, value)
         end
         
+        # Prepares a value coming from the backend for the mapper
+        # @param [Class] type
+        # @param [Object] value
+        # @return [Object] The prepared value
         def value_to_mapper(type, value)
             value
         end
         
-        
+        # Prepares a value that will be used by the backend (see also {#value_for_save} and {#value_for_condition},
+        # which by default call this method, but can be override to do more specific processiong).
+        # @param [Class] type
+        # @param [Object] value
+        # @return [Object] The prepared value
         def prepare_value(type, value)
             return value
         end
         
+        # @return [bool] True if the other storage is of the same class, and has the same connection url
         def ==(storage)
             return false unless self.class == storage.class
             return false unless self.url == storage.url
             return true
         end
         
-        
+        # @return [bool] True if the backend support stransaction
         def supports_transactions?
             return self.class.supports?(:transactions)
         end
         
+        # @return [bool] True if transactions are supported by the backend and enabled in the storage's configuration.
         def transactions_enabled?
             @configuration['enable_transactions'] && supports_transactions?
         end
         
+        # Starts a new transaction on the backend
+        # @return [bool] True if a new transaction was started, false otherwise
         def start_transaction
             return unless transactions_enabled?
             curr[:transaction_nesting] += 1
@@ -213,11 +282,14 @@ module Spider; module Model; module Storage
             return true
         end
         
-        # May be implemented by subclasses.
+        # @abstract
+        # Implemented by subclasses to interact with the backend
         def do_start_transaction
            raise StorageException, "The current storage does not support transactions" 
         end
         
+        # Starts a transaction, or increases transaction nesting.
+        # @return [bool] True if a transaction was already active, false otherwise
         def in_transaction
             if in_transaction?
                 curr[:transaction_nesting] += 1
@@ -228,11 +300,15 @@ module Spider; module Model; module Storage
             end
         end
         
+        # @return [bool] True if a transaction is currently active
         def in_transaction?
             return false
         end
         
         
+        # Commits the current transaction
+        # @return [bool] True if the transaction was successfully committed, false if transactions are not enabled
+        #                (Raises a StorageException if transactions are supported but were not started)
         def commit
             return false unless transactions_enabled?
             raise StorageException, "Commit without a transaction" unless in_transaction?
@@ -240,6 +316,9 @@ module Spider; module Model; module Storage
             commit!
         end
         
+        # Commits the current transaction, or decreases transaction nesting.
+        # @return [bool] True if the transaction was successfully committed, false if transactions are not enabled
+        #                (Raises a StorageException if transactions are supported but were not started)
         def commit_or_continue
             return false unless transactions_enabled?
             raise StorageException, "Commit without a transaction" unless in_transaction?
@@ -252,6 +331,8 @@ module Spider; module Model; module Storage
             end
         end
         
+        # Commits current transaction, resets transaction nesting, and releases the connection.
+        # @return [void]
         def commit!
             Spider.logger.debug("#{self.class.name} commit connection #{curr[:conn].object_id}")
             curr[:transaction_nesting] = 0
@@ -259,16 +340,23 @@ module Spider; module Model; module Storage
             release
         end
         
+        # @abstract
+        # Implemented by subclasses to interact with the backend
+        # @return [void]
         def do_commit
             raise StorageException, "The current storage does not support transactions" 
         end
         
+        # Rolls back the current transaction. Raises an error if in a nested transaction.
+        # @return [void]
         def rollback
             raise "Can't rollback in a nested transaction" if curr[:transaction_nesting] > 1
             return rollback_savepoint(curr[:savepoints].last) unless curr[:savepoints].empty?
             rollback!
         end
         
+        # Rolls back the current transaction, regardless of transaction nesting, and releases the connection
+        # @return [void]
         def rollback!
             curr[:transaction_nesting] = 0
             Spider.logger.debug("#{self.class.name} rollback")
@@ -277,14 +365,23 @@ module Spider; module Model; module Storage
             release
         end
         
+        # @abstract
+        # Implemented by subclasses to interact with the backend
+        # @return [void]
         def do_rollback
             raise StorageException, "The current storage does not support transactions" 
         end
         
+        # Creates a new savepoint
+        # @param [String] name
+        # @return [void]
         def savepoint(name)
             curr[:savepoints] << name
         end
         
+        # Rolls back a savepoint
+        # @param [String] name
+        # @return [void]
         def rollback_savepoint(name=nil)
             if name
                 curr[:savepoints] = curr[:savepoints][0,(curr[:savepoints].index(name))]
@@ -296,30 +393,47 @@ module Spider; module Model; module Storage
         
         # Utility methods
         
+        # @param [String] name Sequence name
+        # @return [String] Path to the sequence file
         def sequence_file_path(name)
             path = File.join(Spider.paths[:var], 'sequences', name)
             return path
         end
         
+        # @param [String] name Sequence name
+        # @return [bool] True if the sequence file exists
         def sequence_exists?(name)
             File.exist?(sequence_file_path(name))
         end
         
+        # Creates a new sequence
+        # @param [String] name Sequence name
+        # @param [Fixnum] start
+        # @param [Fixnum] increment
+        # @return [void]
         def create_sequence(name, start=1, increment=1)
             sequence_next(name, start-1, increment)
         end
         
+        # @return [String] A new UUID
         def generate_uuid
             Spider::DataTypes::UUID.generate
         end
             
-        
+        # Updates a sequence
+        # @param [String] name Sequence name
+        # @param [Fixnum] val New value for the sequence
+        # @return [Fixnum] New value for the sequence
         def update_sequence(name, val)
             # not an alias because the set value behaviour of next_sequence isn't expected in subclasses
             sequence_next(name, val)
         end
         
         # Increments a named sequence and returns the new value
+        # @param [String] name Sequence name
+        # @param [Fixnum] newval New value for the sequence
+        # @param [Fixnum] increment
+        # @return [Fixnum] New value for the sequence
         def sequence_next(name, newval=nil, increment=1)
             path = sequence_file_path(name)
             FileUtils.mkpath(File.dirname(path))
@@ -360,6 +474,7 @@ module Spider; module Model; module Storage
     #   Exceptions                #
     ###############################
     
+    # Exception for Storage related errors
     class StorageException < RuntimeError
     end
     

data/lib/spiderfw/model/storage/db/db_storage.rb

@@ -6,8 +6,7 @@ module Spider; module Model; module Storage; module Db
     
     # Represents a DB connection, and provides methods to execute structured queries on it.
     # This is the class that generates the actual SQL; vendor specific extensions may override the 
-    # generic SQL methods.
-    
+    # generic SQL methods.    
     class DbStorage < Storage::BaseStorage
         @reserved_keywords = ['from', 'order', 'where', 'to']
         @type_synonyms = {}
@@ -26,15 +25,19 @@ module Spider; module Model; module Storage; module Db
 
         class << self
             # An Array of keywords that can not be used in schema names.
+            # @return [Array]
             attr_reader :reserved_keywords
             # An Hash of DB type equivalents.
+            # @return [Hash]
             attr_reader :type_synonyms
-            # Type conversions which do not lose data. See also #safe_schema_conversion?
+            # Type conversions which do not lose data. See also {#safe_schema_conversion?}
+            # @return [Hash]
             attr_reader :safe_conversions
             # Types for which we can safely ignore length in conversions
+            # @return [Array]
             attr_reader :fixed_length_types
 
-
+            # @return [Symbol] A label for the storage's class.
             def storage_type
                 :db
             end

data/lib/spiderfw/model/storage.rb

@@ -1,10 +1,17 @@
 #require 'spiderfw/model/storage/db/connectors/odbc'
 
 module Spider; module Model
-    
+
+    # The namespace for classes related to storage.
+    # 
+    # See {BaseStorage}.
     module Storage
         
         
+        # Returns an instance of a BaseStorage subclass, according to type and type-specific url
+        # @param [String] type The type of storage. Can be 'db' (for DataBase storages),
+        #                      'doc' (for Document storages), or 'stub' (for a Test stub).
+        # @param [String] url  A connection url, specific to the storage.
         def self.get_storage(type, url)
             Thread.current[:storages] ||= {}
             Thread.current[:storages][type] ||= {}

data/lib/spiderfw/setup/spider_setup_wizard.rb

@@ -195,15 +195,17 @@ module Spider
                         url_db_type = $1
                     end
                 end
-                ask _("Database type: "), :db_type, :choices => ['mysql', 'oracle'], \
+                ask _("Database type: "), :db_type, :choices => ['sqlite', 'mysql', 'oracle'], \
                     :default => url_db_type
                 break unless @db_type
-                db = wizard_instance(get_db_wizard(@db_type))
-                db.parse_url(conf["url"]) if conf && conf["url"] && @db_type == url_db_type
-                db.run
-                editor = Spider.config.get_editor
-                editor.set('storages', @db_label, 'url', db.get_url)
-                editor.save
+                unless @db_type == 'sqlite'
+                    db = wizard_instance(get_db_wizard(@db_type))
+                    db.parse_url(conf["url"]) if conf && conf["url"] && @db_type == url_db_type
+                    db.run
+                    editor = Spider.config.get_editor
+                    editor.set('storages', @db_label, 'url', db.get_url)
+                    editor.save
+                end
                 puts _("Configuration saved.")
             end