class EasyExist::DB

Responsible for communicating with the eXist-db server

Public Class Methods

new(url, opts = {}) click to toggle source

Initializes an EasyExist::DB.

@param url [String] the url to the eXist-db server, include protocol. @param opts [Hash] options to initialize the DB with. @option opts :collection [String] The collection for which all GET, PUT and DELETE requests will be relative to. @option opts :username [String] Username for Basic HTTP Authentication. @option opts :password [String] Password for Basic HTTP Authentication. @return [EasyExist::DB] an instance of an EasyExist::DB.

# File lib/easy-exist/db.rb, line 14
def initialize(url, opts = {})
        validate_opts(opts)
        @default_opts = { base_uri: url + "/exist/rest/db#{opts[:collection] ||= ''}" }
        if(opts[:username] && opts[:password])
                @default_opts[:basic_auth] = { username: opts[:username], password: opts[:password] }
        end
end

Public Instance Methods

delete(document_uri) click to toggle source

Deletes the document at the specified URI from the store

@param document_uri [String] the URI of the document to delete. relative to the collection specified on initialization otherwise ‘/db’. @return [HTTParty::Response] the response object

# File lib/easy-exist/db.rb, line 49
def delete(document_uri)
        validate_uri(document_uri)
        res = HTTParty.delete(document_uri, @default_opts)
        res.success? ? res : handle_error(res)
end
execute_stored_query(query_uri) click to toggle source

Returns the results of running the query stored at the specified URI

@param query_uri [String] the URI of the query to run @return [String] the query results

# File lib/easy-exist/db.rb, line 96
def execute_stored_query(query_uri)
        self.get(query_uri)
end
exists?(document_uri) click to toggle source

Determines if the document at the specified URI exists in the store

@param document_uri [String] the uri of the document to check. relative to the collection specified on initialization otherwise ‘/db’. @return [TrueClass | FalseClass]

# File lib/easy-exist/db.rb, line 60
def exists?(document_uri)
        validate_uri(document_uri)
        HTTParty.get(document_uri, @default_opts).success?
end
get(document_uri) click to toggle source

Retrieves the document at the specified URI from the store.

@param document_uri [String] the URI of the document to retrieve. relative to the collection specified on initialization otherwise ‘/db’. @return [String] the contents of the document at ‘document_uri’

# File lib/easy-exist/db.rb, line 27
def get(document_uri)
        validate_uri(document_uri)
        res = HTTParty.get(document_uri, @default_opts)
        res.success? ? res.body      : handle_error(res)
end
put(document_uri, document) click to toggle source

Puts the given document content at the specified URI

@param document_uri [String] the URI at wich to store the document. relative to the collection specified on initialization otherwise ‘/db’. @return [HTTParty::Response] the response object

# File lib/easy-exist/db.rb, line 38
def put(document_uri, document)
        validate_uri(document_uri)
        res = put_document(document_uri, document, "application/xml")
        res.success? ? res : handle_error(res)
end
query(query, opts = {}) click to toggle source

Runs the given XQuery against the store and returns the results

@param query [String] XQuery to run against the store @param opts [Hash] options for the query request. @option opts :start [Integer] Index of first item to be returned. @option opts :max [Integer] The maximum number of items to be returned. @return [String] the query results

# File lib/easy-exist/db.rb, line 72
def query(query, opts = {})
        body = EasyExist::QueryRequest.new(query, opts).body
        res = HTTParty.post("", @default_opts.merge({
                body: body,
                headers: { 'Content-Type' => 'application/xml', 'Content-Length' => body.length.to_s }
        }))
        res.success? ? res.body : handle_error(res)
end
store_query(query_uri, query) click to toggle source

Stores the given query at the specified URI

@param query_uri [String] the URI of the query to run @param query [String] the query body @return [HTTParty::Response] the response object

# File lib/easy-exist/db.rb, line 86
def store_query(query_uri, query)
        validate_uri(query_uri)
        res = put_document(query_uri, query, "application/xquery")
        res.success? ? res : handle_error(res)
end

Private Instance Methods

handle_error(res) click to toggle source

Raises an error based on a HTTParty::Response. HTTParty:Response objects contain a reference to the Net::HTTResponse object. Where a request is unsuccessful, the reference can be raised as an exception for clients to rescue and decide on next steps.

@param res [HTTParty::Response] the response

# File lib/easy-exist/db.rb, line 107
def handle_error(res)
        res.response.value
end
put_document(uri, document, content_type) click to toggle source

Stores a document at the specified URI and with the specified content type

@param uri [String] the URI under which to store the document @param document [String] the document body @param content_type [String] the MIME Type of the document @return [HTTParty::Response] the response object

# File lib/easy-exist/db.rb, line 131
def put_document(uri, document, content_type)
        HTTParty.put(uri, @default_opts.merge({
                body: document,
                headers: { "Content-Type" => content_type},
        }))
end
validate_opts(opts) click to toggle source

Raises an error if any of the given opts are invalid

@param opts [Hash] options to validate.

# File lib/easy-exist/db.rb, line 121
def validate_opts(opts)
        validate_uri(opts[:collection]) unless opts[:collection].nil? || opts[:collection].empty?
end
validate_uri(uri) click to toggle source

Raises an error if the specified URI does not start with a ‘/’

@param uri [String] the URI to validate

# File lib/easy-exist/db.rb, line 114
def validate_uri(uri)
        raise ArgumentError, 'URI must contain preceding "/"' if uri[0] != '/';
end