ashikawa-core 0.10.0 → 0.11.0

data/lib/ashikawa-core/database.rb

@@ -12,6 +12,7 @@ module Ashikawa
   module Core
     # An ArangoDB database
     class Database
+      # ArangoDB defines two different kinds of collections: Document and Edge Collections
       COLLECTION_TYPES = {
         document: 2,
         edge: 3
@@ -58,6 +59,64 @@ module Ashikawa
         @connection = configuration.connection
       end
 
+      # Create the database
+      #
+      # @example Create a new database with the name 'ashikawa'
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = 'http://localhost:8529/_db/ashikawa'
+      #   end
+      #   database.create
+      def create
+        @connection.send_request_without_database_suffix('database', post: { name: @connection.database_name })
+      end
+
+      # Drop the database
+      #
+      # @example Drop a new database with the name 'ashikawa'
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = 'http://localhost:8529/_db/ashikawa'
+      #   end
+      #   database.drop
+      def drop
+        @connection.send_request_without_database_suffix("database/#{name}", delete: {})
+      end
+
+      # Truncate all collections of the database
+      #
+      # @example Truncate all collections of the database
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = 'http://localhost:8529'
+      #   end
+      #   database.truncate
+      def truncate
+        collections.each { |collection| collection.truncate }
+      end
+
+      # The name of the database
+      #
+      # @return [String]
+      # @api public
+      # @example Get the name of the databasse
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = 'http://localhost:8529/_api/ashikawa'
+      #   end
+      #   database.name # => 'ashikawa'
+      def name
+        @connection.database_name
+      end
+
+      # Get a list of all databases
+      #
+      # @api public
+      # @example Get a list of all databases
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = 'http://localhost:8529'
+      #   end
+      #   database.all_databases # => ['_system']
+      def all_databases
+        send_request('database')['result']
+      end
+
       # Returns a list of all non-system collections defined in the database
       #
       # @return [Array<Collection>]
@@ -131,8 +190,8 @@ module Ashikawa
       # Create a new Transaction for this database
       #
       # @param [String] action The JS action you want to execute
-      # @options collections [Array<String>] :read The collections you want to read from
-      # @options collections [Array<String>] :write The collections you want to write to
+      # @option collections [Array<String>] :read The collections you want to read from
+      # @option collections [Array<String>] :write The collections you want to write to
       # @return [Object] The result of the transaction
       # @api public
       # @example Create a new Transaction

data/lib/ashikawa-core/error_response.rb

@@ -28,6 +28,17 @@ module Ashikawa
       # All status codes for server errors
       ServerErrorStatuses = 500...599
 
+      # On completion of the request raise errors depending on the status
+      #
+      # @raise [BadSyntax] If the status code is a 400
+      # @raise [AuthenticationFailed] If the status code is a 401
+      # @raise [DocumentNotFoundException] If the status code is 404 and a document was requested
+      # @raise [CollectionNotFoundException] If the status code is 404 and a collection was requested
+      # @raise [IndexNotFoundException] If the status code is 404 and an index was requested
+      # @raise [ResourceNotFoundError] If the status code is 404 and any other resource was requested
+      # @raise [ClientError] If the status code is any other 4XX code
+      # @raise [ServerError] If the status code is any of the 5XX codes
+      # @return nil
       def on_complete(env)
         @body = env[:body]
         @url = env[:url]
@@ -49,7 +60,7 @@ module Ashikawa
       # @return nil
       # @api private
       def bad_syntax
-        raise BadSyntax
+        raise BadSyntax, error
       end
 
       # Raise an Authentication Failed Error
@@ -99,10 +110,10 @@ module Ashikawa
       # @return [String] The formatted error message
       # @api private
       def error
-        "#{@body['errorNum']}: #{@body["errorMessage"]}"
+        "#{@body['errorNum']}: #{@body['errorMessage']}"
       end
     end
 
-    Faraday.register_middleware :response, error_response: -> { ErrorResponse }
+    Faraday::Response.register_middleware error_response: -> { ErrorResponse }
   end
 end

data/lib/ashikawa-core/exceptions/client_error.rb

@@ -5,11 +5,11 @@ module Ashikawa
     class ClientError < RuntimeError
       # Create a new instance
       #
-      # @param [Integer] status
+      # @param [Fixnum] status_code
       # @return RuntimeError
       # @api private
-      def initialize(description)
-        @description = description
+      def initialize(status_code)
+        @status_code = status_code
       end
 
       # String representation of the exception
@@ -17,7 +17,7 @@ module Ashikawa
       # @return String
       # @api private
       def to_s
-        @description
+        @status_code
       end
     end
   end

data/lib/ashikawa-core/exceptions/client_error/bad_syntax.rb

@@ -9,7 +9,8 @@ module Ashikawa
       #
       # @return RuntimeError
       # @api private
-      def initialize
+      def initialize(message = 'Status 400: The syntax of the request was bad')
+        @message = message
         super(400)
       end
 
@@ -18,7 +19,7 @@ module Ashikawa
       # @return String
       # @api private
       def to_s
-        'Status 400: The syntax of the request was bad'
+        @message
       end
     end
   end

data/lib/ashikawa-core/exceptions/server_error.rb

@@ -5,11 +5,11 @@ module Ashikawa
     class ServerError < RuntimeError
       # Create a new instance
       #
-      # @param [Integer] status
+      # @param [Fixnum] status_code
       # @return RuntimeError
       # @api private
-      def initialize(description)
-        @description = description
+      def initialize(status_code)
+        @status_code = status_code
       end
 
       # String representation of the exception
@@ -17,7 +17,7 @@ module Ashikawa
       # @return String
       # @api private
       def to_s
-        @description
+        @status_code
       end
     end
   end

data/lib/ashikawa-core/key_options.rb

@@ -14,7 +14,7 @@ module Ashikawa
 
       # A specific start value
       #
-      # @return Integer
+      # @return Fixnum
       # @api public
       # @example Get the type of the KeyOptions
       #   keyOptions = KeyOptions.new({ :offset => 12 })
@@ -23,7 +23,7 @@ module Ashikawa
 
       # Size of increment steps
       #
-      # @return Integer
+      # @return Fixnum
       # @api public
       # @example Get the type of the KeyOptions
       #   keyOptions = KeyOptions.new({ :increment => 12 })
@@ -41,6 +41,7 @@ module Ashikawa
 
       # Create a new KeyOptions object from the raw key options
       #
+      # @param [Hash] raw_key_options The raw options for the key returned from the server
       # @api public
       # @example Create a new KeyOptions object
       #   KeyOptions.new({ :type => :autoincrement })

data/lib/ashikawa-core/query.rb

@@ -11,13 +11,14 @@ module Ashikawa
     class Query
       extend Forwardable
 
+      # For each simple query define the allowed attributes for filtering
       ALLOWED_KEYS_FOR_PATH = {
         'simple/all'           => [:limit, :skip, :collection],
         'simple/by-example'    => [:limit, :skip, :example, :collection],
         'simple/near'          => [:latitude, :longitude, :distance, :skip, :limit, :geo, :collection],
         'simple/within'        => [:latitude, :longitude, :radius, :distance, :skip, :limit, :geo, :collection],
         'simple/range'         => [:attribute, :left, :right, :closed, :limit, :skip, :collection],
-        'cursor'               => [:query, :count, :batch_size, :collection],
+        'cursor'               => [:query, :count, :batch_size, :collection, :bind_vars],
         'query'                => [:query],
         'simple/first-example' => [:example, :collection]
       }
@@ -40,8 +41,8 @@ module Ashikawa
       # Retrieves all documents for a collection
       #
       # @note It is advised to NOT use this method due to possible HUGE data amounts requested
-      # @option options [Integer] :limit limit the maximum number of queried and returned elements.
-      # @option options [Integer] :skip skip the first <n> documents of the query.
+      # @option options [Fixnum] :limit limit the maximum number of queried and returned elements.
+      # @option options [Fixnum] :skip skip the first <n> documents of the query.
       # @return [Cursor]
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
       # @api public
@@ -56,8 +57,8 @@ module Ashikawa
       #
       # @option example [Hash] a Hash with data matching the documents you are looking for.
       # @option options [Hash] a Hash with additional settings for the query.
-      # @option options [Integer] :limit limit the maximum number of queried and returned elements.
-      # @option options [Integer] :skip skip the first <n> documents of the query.
+      # @option options [Fixnum] :limit limit the maximum number of queried and returned elements.
+      # @option options [Fixnum] :skip skip the first <n> documents of the query.
       # @return [Cursor]
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
       # @api public
@@ -85,12 +86,12 @@ module Ashikawa
 
       # Looks for documents in a collection based on location
       #
-      # @option options [Integer] :latitude Latitude location for your search.
-      # @option options [Integer] :longitude Longitude location for your search.
-      # @option options [Integer] :skip The documents to skip in the query.
-      # @option options [Integer] :distance If given, the attribute key used to store the distance.
-      # @option options [Integer] :limit The maximal amount of documents to return (default: 100).
-      # @option options [Integer] :geo If given, the identifier of the geo-index to use.
+      # @option options [Fixnum] :latitude Latitude location for your search.
+      # @option options [Fixnum] :longitude Longitude location for your search.
+      # @option options [Fixnum] :skip The documents to skip in the query.
+      # @option options [Fixnum] :distance If given, the attribute key used to store the distance.
+      # @option options [Fixnum] :limit The maximal amount of documents to return (default: 100).
+      # @option options [Fixnum] :geo If given, the identifier of the geo-index to use.
       # @return [Cursor]
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
       # @api public
@@ -103,13 +104,13 @@ module Ashikawa
 
       # Looks for documents in a collection within a radius
       #
-      # @option options [Integer] :latitude Latitude location for your search.
-      # @option options [Integer] :longitude Longitude location for your search.
-      # @option options [Integer] :radius Radius around the given location you want to search in.
-      # @option options [Integer] :skip The documents to skip in the query.
-      # @option options [Integer] :distance If given, the attribute key used to store the distance.
-      # @option options [Integer] :limit The maximal amount of documents to return (default: 100).
-      # @option options [Integer] :geo If given, the identifier of the geo-index to use.
+      # @option options [Fixnum] :latitude Latitude location for your search.
+      # @option options [Fixnum] :longitude Longitude location for your search.
+      # @option options [Fixnum] :radius Radius around the given location you want to search in.
+      # @option options [Fixnum] :skip The documents to skip in the query.
+      # @option options [Fixnum] :distance If given, the attribute key used to store the distance.
+      # @option options [Fixnum] :limit The maximal amount of documents to return (default: 100).
+      # @option options [Fixnum] :geo If given, the identifier of the geo-index to use.
       # @return [Cursor]
       # @api public
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
@@ -122,12 +123,12 @@ module Ashikawa
 
       # Looks for documents in a collection with an attribute between two values
       #
-      # @option options [Integer] :attribute The attribute path to check.
-      # @option options [Integer] :left The lower bound
-      # @option options [Integer] :right The upper bound
-      # @option options [Integer] :closed If true, the interval includes right
-      # @option options [Integer] :skip The documents to skip in the query (optional).
-      # @option options [Integer] :limit The maximal amount of documents to return (optional).
+      # @option options [Fixnum] :attribute The attribute path to check.
+      # @option options [Fixnum] :left The lower bound
+      # @option options [Fixnum] :right The upper bound
+      # @option options [Fixnum] :closed If true, the interval includes right
+      # @option options [Fixnum] :skip The documents to skip in the query (optional).
+      # @option options [Fixnum] :limit The maximal amount of documents to return (optional).
       # @return [Cursor]
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
       # @api public
@@ -141,13 +142,18 @@ module Ashikawa
       # Send an AQL query to the database
       #
       # @param [String] query
-      # @option options [Integer] :count Should the number of results be counted?
-      # @option options [Integer] :batch_size Set the number of results returned at once
+      # @option options [Fixnum] :count Should the number of results be counted?
+      # @option options [Fixnum] :batch_size Set the number of results returned at once
       # @return [Cursor]
       # @api public
       # @example Send an AQL query to the database
       #   query = Ashikawa::Core::Query.new(collection)
       #   query.execute('FOR u IN users LIMIT 2') # => #<Cursor id=33>
+      # @example Usage of bind variables
+      #    db = Ashikawa::Core::Database.new(){|conf| conf.url="http://127.0.0.1:8529"}
+      #    query = 'FOR t IN TRAVERSAL(imdb_vertices, imdb_edges, "imdb_vertices/759", "outbound", {maxDepth: 2})' +
+      #     'FILTER t.vertex.genre == @foo RETURN t'
+      #    db.query.execute(query, bind_vars: {'foo' => 'Comedy'}).to_a
       def execute(query, options = {})
         wrapped_request('cursor', :post, options.merge({ query: query }))
       end
@@ -187,8 +193,8 @@ module Ashikawa
 
       # Removes the keys that are not allowed from an object
       #
+      # @param [String] path The path for the request
       # @param [Hash] options
-      # @param [Array<Symbol>] allowed_keys
       # @return [Hash] The filtered Hash
       # @api private
       def prepare_request(path, options)
@@ -213,7 +219,6 @@ module Ashikawa
       #
       # @param [String] path The path for the request
       # @param [Hash] request The data send to the database
-      # @param [Array<Symbol>] allowed_keys The keys allowed for this request
       # @return [String] Server response
       # @raise [NoCollectionProvidedException] If you provided a database, no collection
       # @api private
@@ -226,7 +231,6 @@ module Ashikawa
       # @param [String] path The path for the request
       # @param [Symbol] request_method The request method to perform
       # @param [Hash] request The data send to the database
-      # @param [Array] allowed_keys Keys allowed in request, if nil: All keys are allowed
       # @return [Cursor]
       # @api private
       def wrapped_request(path, request_method, request)

data/lib/ashikawa-core/status.rb

@@ -3,10 +3,19 @@ module Ashikawa
   module Core
     # Wrapper around the status of a collection
     class Status
+      # ArangoDB Status for a new born collection
       STATUS_NEW_BORN       = 1
+
+      # ArangoDB Status for a collection that is unloaded
       STATUS_UNLOADED       = 2
+
+      # ArangoDB Status for a collection that is loaded
       STATUS_LOADED         = 3
+
+      # ArangoDB Status for a collection that is being unloaded
       STATUS_BEING_UNLOADED = 4
+
+      # Highest ArangoDB Status that means that the collection is not corrupted
       MAX_UNCORRUPTED       = 5
 
       # Create a wrapper around a given status

data/lib/ashikawa-core/transaction.rb

@@ -45,7 +45,7 @@ module Ashikawa
 
       # An optional numeric value used to set a timeout for waiting on collection locks
       #
-      # @return [Integer]
+      # @return [Fixnum]
       # @api public
       # @example Check how long the lock timeout is
       #   transaction.lock_timeout # => 30
@@ -55,7 +55,7 @@ module Ashikawa
 
       # An optional numeric value used to set a timeout for waiting on collection locks
       #
-      # @param [Integer] lock_timeout
+      # @param [Fixnum] timeout
       # @api public
       # @example Set the lock timeout to 30
       #   transaction.lock_timeout = 30
@@ -84,7 +84,7 @@ module Ashikawa
 
       # Execute the transaction
       #
-      # @param [Object] action_params The parameters for the defined action
+      # @param [Object] action_parameters The parameters for the defined action
       # @return Object The result of the transaction
       # @api public
       # @example Run a Transaction

data/lib/ashikawa-core/version.rb

@@ -2,6 +2,6 @@
 module Ashikawa
   module Core
     # Current version of Ashikawa::Core
-    VERSION = '0.10.0'
+    VERSION = '0.11.0'
   end
 end

data/spec/acceptance/basic_spec.rb

@@ -15,6 +15,12 @@ describe 'Basics' do
       subject['new_name'].delete
     end
 
+    it 'should have one more database if a database with random name is created' do
+      expect {
+        database_with_random_name.create
+      }.to change { DATABASE.all_databases.length }.by(1)
+    end
+
     it 'should create and delete collections' do
       subject.collections.each { |collection| collection.delete }
       subject['collection_1']
@@ -27,12 +33,12 @@ describe 'Basics' do
 
     it 'should create a non-volatile collection by default' do
       subject.create_collection('nonvolatile_collection')
-      expect(subject['nonvolatile_collection'].volatile?).to be_false
+      expect(subject['nonvolatile_collection'].volatile?).to be_falsey
     end
 
     it 'should create a volatile collection' do
       subject.create_collection('volatile_collection', is_volatile: true)
-      expect(subject['volatile_collection'].volatile?).to be_true
+      expect(subject['volatile_collection'].volatile?).to be_truthy
     end
 
     it 'should create an autoincrementing collection' do
@@ -72,11 +78,11 @@ describe 'Basics' do
 
     it 'should be possible to load and unload collections' do
       my_collection = subject['test_collection']
-      expect(my_collection.status.loaded?).to be_true
+      expect(my_collection.status.loaded?).to be_truthy
       my_collection.unload
       my_id = my_collection.id
       subject[my_id]
-      expect(subject[my_id].status.loaded?).to be_false
+      expect(subject[my_id].status.loaded?).to be_falsey
     end
 
     it 'should be possible to get figures' do
@@ -96,9 +102,9 @@ describe 'Basics' do
     it 'should change and receive information about waiting for sync' do
       my_collection = subject['my_collection']
       my_collection.wait_for_sync = false
-      expect(my_collection.wait_for_sync?).to be_false
+      expect(my_collection.wait_for_sync?).to be_falsey
       my_collection.wait_for_sync = true
-      expect(my_collection.wait_for_sync?).to be_true
+      expect(my_collection.wait_for_sync?).to be_truthy
     end
 
     it 'should be possible to get information about the number of documents' do
@@ -107,7 +113,7 @@ describe 'Basics' do
       empty_collection.create_document(name: 'testname', age: 27)
       empty_collection.create_document(name: 'anderer name', age: 28)
       expect(empty_collection.length).to eq(2)
-      empty_collection.truncate!
+      empty_collection.truncate
       expect(empty_collection.length).to eq(0)
     end
 
@@ -155,7 +161,7 @@ describe 'Basics' do
 
     it 'should be possible to get a single attribute by AQL query' do
       collection = subject['documenttests']
-      collection.truncate!
+      collection.truncate
       collection.create_document(name: 'The Dude', bowling: true)
 
       expect(subject.query.execute('FOR doc IN documenttests RETURN doc.name').to_a.first). to eq 'The Dude'