eXistAPI 0.0.0 → 1.0.0

data/lib/collection.rb

@@ -3,12 +3,27 @@ require 'document'
 
 class Collection
 
+  #name of the collection
   attr_reader :name
+  #owner of the collection
   attr_reader :owner
+  #owner group of the collection
   attr_reader :group
+  #permissions of the collection
   attr_reader :permissions
+  #descendent collection of the collection
   attr_reader :childCollection
     
+  #Creates new collection.
+  #
+  # * *Args*    :
+  #   - +client+ -> e.g. ExistAPI.new("http://localhost:8080/exist/xmlrpc", "admin", "password")    
+  #   - +collectionName+ -> /db/data/cities/
+  # * *Returns* :
+  #   -new instance of collection
+  # * *Raises* :
+  #   - +nothing+ ->
+  #
   def initialize(client, collectionName)
     @client = client
     load(collectionName)
@@ -16,20 +31,56 @@ class Collection
     raise e  
   end
 
+  #Returns string of collection. That inclunde permissions, owner, group and name.
+  #
+  # * *Args*    :
+  #   - +none+
+  # * *Returns* :
+  #   -string of collection
+  # * *Raises* :
+  #   - +nothing+
+  #
   def to_s()
     return "#{@permissions} #{@owner} #{@group} #{@name}"
   end
 
+  #Yield each document from collection.
+  #
+  # * *Args*    :
+  #   - +none+
+  # * *Returns* :
+  #   -documents
+  # * *Raises* :
+  #   - +nothing+
+  #
   def documents
     @documents.each { |d| yield d }
   end
   
-  def docs    #returns string array of all documents in collection
+  #Returns string array of all documents in collection
+  #
+  # * *Args*    :
+  #   - +none+
+  # * *Returns* :
+  #   -array of strings
+  # * *Raises* :
+  #   - +nothing+
+  #
+  def docs    
     ds = []
     @documents.each{ |d| ds.push(d.name)}
     return ds
   end
 
+  #Returns instance of collection's child specified by name.
+  #
+  # * *Args*    :
+  #   - +key+ -> name of the child
+  # * *Returns* :
+  #   -instance of collection's child (document or collection)
+  # * *Raises* :
+  #   - +nothing+
+  #
   def [](key)
     @documents.each { |d|
       return d if key == d.name 
@@ -38,7 +89,16 @@ class Collection
   end
 
   protected
-
+  
+  #Loads collection from db.
+  #
+  # * *Args*    :
+  #   - +collectionName+ -> e.g. /db/data/cities/
+  # * *Returns* :
+  #   - instance of collection
+  # * *Raises* :
+  #   - +ExistException+ -> Failed to load Collection
+  #
   def load(collectionName)
     resp = @client.call("getCollectionDesc", collectionName)
     @name = resp['name']+"/"

data/lib/document.rb

@@ -1,11 +1,28 @@
 class Document
 
+  #path of the document
   attr_reader :path
+  #name of the document
   attr_reader :name
+  #owner of the document
   attr_reader :owner
+  #owner group of the document
   attr_reader :group
+  #permissions of the document
   attr_reader :permissions
-
+  
+  #Creates new instance of document
+  #
+  # * *Args*    :
+  #   - +client+ -> e.g. ExistAPI.new("http://localhost:8080/exist/xmlrpc", "admin", "password")    
+  #   - +hash+ -> hash, name -> "name of the document"
+  #   - +colname+ -> name of the collection
+  # * *Returns* :
+  #   -instance of document
+  # * *Raises* :
+  #   - +nothing+
+  # * *Example* :
+  #   - Document.new(api, hash, collection_path)
   def initialize(client, hash, colname)
     @client = client
     @path = colname + hash['name']
@@ -17,11 +34,29 @@ class Document
   rescue  => e
     raise e  
   end
-
+  
+  #Returns string of document. That inclunde permissions, owner, group and name.
+  #
+  # * *Args*    :
+  #   - +none+
+  # * *Returns* :
+  #   -string of collection
+  # * *Raises* :
+  #   - +nothing+
+  #
   def to_s
     return "#{@permissions} #{@owner} #{@group} #{@name}"
   end
 
+  #Returns content of document in db. Usually document is xml.
+  #Retrieves a document from the database.
+  # * *Args*    :
+  #   - +none+
+  # * *Returns* :
+  #   - the result of call
+  # * *Raises* :
+  #   - +ExistException+ -> Failed to load content of Document
+  #
   def content
     options = { "indent" => "yes", "encoding" => "UTF-8",
       "expand-xincludes" => "yes" }

data/lib/eXistAPI.rb

@@ -1,18 +1,52 @@
 require "xmlrpc/client"
+$:.unshift(".")
 require 'collection'
 
+#ExistAPI is comunication interface to eXist-db based on XML-RPC. With eXistAPI 
+#you are able to create, delete or get collections or retrieve whole content of 
+#documents or part of it by querying. 
+#Also with eXistAPI you can work with documents stored in eXist-db. 
+#You can insert, replace, rename and delete nodes or change values.
+#To query use xQuery or xPath.
+#
+#
+# ==== Examples
+#db = ExistAPI.new("http://localhost:8080/exist/xmlrpc", "admin", "admin")
+#puts db.existscollection?("db")
 class ExistAPI
+  
+  #Create new instance of ExistAPI.
+  #
   #example ExistAPI.new("http://localhost:8080/exist/xmlrpc", "admin", "password")    
+  #
+  # * *Args*    :
+  #   - +uri+ -> uri of the db server
+  #   - +username+ -> username
+  #   - +password+  -> password to specified username
+  # * *Returns* :
+  #   - new instance of ExistAPI
+  # * *Raises* :
+  #   - +ExistException+ -> Database login failed
+  #
   def initialize(uri = nil , username = nil, password = nil)
     @uri = uri
     @username = username
     @password = password
     @parameters = { "encoding" => "UTF-8", "indent" => "yes"}
-    #outputoptions = { "encoding" => "UTF-8", "indent" => "yes"}
     connect
   end
 
   private
+
+  #Creates collection with name in parrent collection(optionaly)#
+  #
+  # * *Args*    :
+  #   - +name+ -> the name of collection
+  # * *Returns* :
+  #   - the result of call
+  # * *Raises* :
+  #   - +ExistException+ -> Database login failed
+  #
   def connect
     @client = XMLRPC::Client.new2(@uri)
     @client.user=(@username)
@@ -24,17 +58,47 @@ class ExistAPI
     raise ExistException.new("Database login failed", 1), caller
   end
   
+  #Checks if path starts and ends with "/". If not, adds "/".
+  #
+  # * *Args*    :
+  #   - +path+ -> the path of collection
+  # * *Returns* :
+  #   - Path with "/" at the begging and end.
+  # * *Raises* :
+  #   - +ArgumentError+ -> if any value is nil or negative
+  #
+  def check_slashes(path)
+    if(path[0] != "/")
+      path = "/" + path
+    end
+    if(path[-1] != "/")    #if last is not "/" then add it
+      path += "/"
+    end
+    return path
+  end
+  
+  
   public
   
-  def createcollection(_name, _parent = nil)
-    if (_parent == nil)
+  #Creates collection with name in parrent(optionaly)
+  #
+  # * *Args*    :
+  #   - +name+ -> the name of collection
+  # * *Returns* :
+  #   - the result of call
+  # * *Raises* :
+  #   - +ExistException+ -> if collection is not created.
+  #
+  def createcollection(name, parent_col = nil)
+    name = check_slashes(name)
+    if (parent_col == nil)
       begin
-        result = @client.call("createCollection", _name)
+        result = @client.call("createCollection", name)
         return result
       end
     else
       begin
-        colname = _parent.getname + _name
+        colname = parent_col.name + name
         result = @client.call("createCollection", colname)
         return result
       end
@@ -45,17 +109,34 @@ class ExistAPI
     raise ExistException.new("Failed to create Collection", 2), caller
   end
   
+  #Returns Collection at specified path.
+  #
+  # * *Args*    :
+  #   - +path+ -> Path of the collection in db.
+  # * *Returns* :
+  #   -instance of class Collection.
+  # * *Raises* :
+  #   - +nothing+
+  #
   def getcollection(path)
-    if(path[-1] != "/")    #if last is not "/" then add it
-      path += "/"
-    end
+    path = check_slashes(path)
     col = Collection.new(@client, path)
     return col
   rescue  => e
     raise e  
   end
   
+  #Checks if collection with path exists or not.
+  #
+  # * *Args*    :
+  #   - +path+ -> Path of the collection in db.
+  # * *Returns* :
+  #   -boolean. true -> exists, false -> doesn't exist
+  # * *Raises* :
+  #   - +nothing+
+  #
   def existscollection?(orig_path)
+    orig_path = check_slashes(orig_path)
     collections = orig_path.split("/")
     collections.delete("")
     i=0
@@ -85,9 +166,18 @@ class ExistAPI
     raise e  
   end
 
-  def remove_collection(_name)
-    # boolean removeCollection( String collection)
-    result = @client.call("removeCollection", _name)
+  
+  #Removes collection with specified path.
+  #
+  # * *Args*    :
+  #   - +path+ -> Path of the collection in db.
+  # * *Returns* :
+  #   - the result of call
+  # * *Raises* :
+  #   - +ExistException+ -> if failed to remove collection.
+  #
+  def remove_collection(path)
+    result = @client.call("removeCollection", path)
     return result
   rescue XMLRPC::FaultException => e
     raise e    
@@ -95,6 +185,18 @@ class ExistAPI
     raise ExistException.new("Failed to remove Collection", 3), caller
   end
   
+  #Stores resource to document in db.
+  #Inserts a new document into the database or replace an existing one:
+  #
+  # * *Args*    :
+  #   - +_res+ -> resource which you want to safe. XML content of this document as a UTF-8 encoded byte array.
+  #   - +_docname+ -> name of the document where to safe. Path to the database location where the new document is to be stored.
+  #   - +_overwrite+ -> Set this value to > 0 to automatically replace an existing document at the same location.
+  # * *Returns* :
+  #   - boolean, the result of the call 
+  # * *Raises* :
+  #   - +ExistException+ -> Resource or document name is nil
+  #   - +ExistException+ -> Failed to store resource"
   def storeresource(_res, _docname, _overwrite = 1)
     if ((_res == nil)||(_docname == nil))
       raise ExistException.new("Resource or document name is nil", 4), caller
@@ -110,6 +212,22 @@ class ExistAPI
     end
   end
   
+  #Executes an XQuery and returns a reference identifier to the generated result set. This reference can be used later to retrieve results.
+  #
+  # * *Args*    :
+  #   - +xquery+ -> String xquery. A valid XQuery expression.
+  #   - +parameters+ -> HashMap parameters. The parameters a HashMap values.
+  #sort-expr :
+  #namespaces :
+  #variables :
+  #base-uri :
+  #static-documents :
+  #protected : 
+  # * *Returns* :
+  #   -int, handle of query
+  # * *Raises* :
+  #   - +ExistException+ -> Failed to execute query
+  #
   def execute_query(xquery, parameters = @parameters)
     #puts xquery
     begin
@@ -122,6 +240,18 @@ class ExistAPI
     end
   end
   
+  #Retrieves a single result-fragment from the result-set referenced by resultId. 
+  #The result-fragment is identified by its position in the result-set, which is passed in the parameter pos.
+  #
+  # * *Args*    :
+  #   - +handle+ -> Reference to a result-set as returned by a previous call to executeQuery.
+  #   - +pos+ -> The position of the item in the result-sequence, starting at 0.
+  #   - +parameters+ -> A struct containing key=value pairs to configure the output.
+  # * *Returns* :
+  #   - the result of call
+  # * *Raises* :
+  #   - +ExistException+ -> Failed to retrive resource
+  #
   def retrieve(handle, pos)
     begin
       res = @client.call("retrieve", handle, pos, @parameters)
@@ -133,6 +263,16 @@ class ExistAPI
     end
   end
   
+  #Get the number of hits in the result-set identified by resultId.
+  #example: gethits(handle_id)
+  #
+  # * *Args*    :
+  #   - +handle+ -> Reference to a result-set as returned by a previous call to executeQuery.
+  # * *Returns* :
+  #   -the number of hits
+  # * *Raises* :
+  #   - +ExistException+ -> Failed to get number of hits
+  #
   def get_hits(handle)
     begin
       summary = @client.call("querySummary", handle)
@@ -145,7 +285,24 @@ class ExistAPI
     end
   end
   
-  #<email type="office">andrew@gmail.com</email>, pos = into | following | preceding, expr_single e.g. //address[fname="Andrew"]
+  #Inserts the content sequence specified in expr into the element node passed 
+  #via exprSingle. exprSingle and expr should evaluate to a node set. 
+  #If exprSingle contains more than one element node, the modification will be 
+  #applied to each of the nodes. The position of the insertion is determined by 
+  #the keywords "into", "following" or "preceding":
+  #
+  #
+  # * *Args*    :
+  #   - +expr+ -> The content is appended after the last child node of the specified elements.
+  #   e.g.: <email type="office">andrew@gmail.com</email>, 
+  #   - +pos+ -> The content is inserted immediately after the node specified in exprSingle.
+  #   pos = "into" | "following" | "preceding"
+  #   - +expr_single+ -> The content is inserted before the node specified in exprSingle.
+  #   e.g. '//address[fname="Andrew"]'
+  # * *Returns* :
+  #   -int handle of query
+  # * *Raises* :
+  #   - +nothing+
   def update_insert(expr, pos, expr_single) 
     query = "update insert "+expr+" "+pos+" "+expr_single
     #puts "query #{query}"
@@ -154,6 +311,20 @@ class ExistAPI
     raise e    
   end
   
+  #Replaces the nodes returned by expr with the nodes in exprSingle. 
+  #expr may evaluate to a single element, attribute or text node. 
+  #If it is an element, exprSingle should contain a single element node as well. 
+  #If it is an attribute or text node, the value of the attribute or the text 
+  #node is set to the concatenated string values of all nodes in exprSingle.
+  #
+  # * *Args*    :
+  #   - +expr+ -> e.g.: //fname[. = "Andrew"]
+  #   - +expr_single+ -> <fname>Andy</fname>
+  # * *Returns* :
+  #   -int handle of query
+  # * *Raises* :
+  #   - +nothing+
+  #
   def update_replace(expr, expr_single)
     query = "update replace "+expr+" with "+expr_single
     execute_query(query)
@@ -161,6 +332,18 @@ class ExistAPI
     raise e  
   end
   
+  #Updates the content of all nodes in expr with the items in exprSingle. 
+  #If expr is an attribute or text node, its value will be set to the 
+  #concatenated string value of all items in exprSingle.
+  #
+  # * *Args*    :
+  #   - +expr+ -> "//node()[@id="RockyRacoon"]/@id"
+  #   - +expr_single+ -> '"RockyR"'
+  # * *Returns* :
+  #   -int handle of query
+  # * *Raises* :
+  #   - +nothing+
+  #
   def update_value(expr, expr_single)
     query = "update replace " + expr + " with " + expr_single
     execute_query(query)
@@ -168,6 +351,15 @@ class ExistAPI
     raise e  
   end
   
+  #Removes all nodes in expr from their document.
+  #
+  # * *Args*    :
+  #   - +expr+ -> "//node()[@id="RockyRacoon"]
+  # * *Returns* :
+  #   -int handle of query
+  # * *Raises* :
+  #   - +nothing+
+  #
   def update_delete(expr)
     query = "update delete " + expr
     #puts "query #{query}"
@@ -176,6 +368,18 @@ class ExistAPI
     raise e  
   end
   
+  #Renames the nodes in expr using the string value of the first item in 
+  #exprSingle as the new name of the node. expr should evaluate to a set of 
+  #elements or attributes.
+  #
+  # * *Args*    :
+  #   - +expr+ -> //city
+  #   - +expr_single+ -> "town"
+  # * *Returns* :
+  #   -int handle of query
+  # * *Raises* :
+  #   - +nothing+ ->
+  #
   def update_rename(expr, expr_single)
     query = "update rename " + expr + " as " + expr_single
     #puts "query #{query}"
@@ -184,26 +388,3 @@ class ExistAPI
     raise e  
   end
 end
-
-
-#db = ExistAPI.new("http://localhost:8080/exist/xmlrpc", "admin", "admin")
-#puts db.existscollection?("db")
-
-#client = XMLRPC::Client.new("localhost", "/exist/xmlrpc", 8080)
-
-#-----------------
-#if $*.length < 1 then
-#  puts "usage: collections.rb collection-path"
-#  exit(0)
-#end
-#
-#path = $*[0]
-#collection = Collection.new(client, "/db/pokus/")
-#puts collection.to_s
-#collection.documents { |d| puts d.to_s }
-#
-#doc = collection['books.xml']
-#if doc == nil 
-#  error("document not found")
-#end
-#puts doc.content

data/lib/exist_exception.rb

@@ -29,7 +29,7 @@ class ExistException < RuntimeError
 
 end
 
-#Soupis jednotlivych vyjimek, v zavorce metoda tera tuto vyjimku vyhazuje
+#List of all exception. In brackets is method, that raise mentioned exception.
 #1: Database login failed (DatabaseManager.connect)
 #2: Failed to create Collection (DatabaseManager.createcollection)
 #3: Failed to remove Collection (DatabaseManager.removecollection)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eXistAPI
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-02 00:00:00.000000000 Z
+date: 2012-05-20 00:00:00.000000000 Z
 dependencies: []
 description: ! "API for eXist-db based on XML-RPC. \nAPI is using xQuery, xPath and
   xQuery Update Facility."