rdbxml 0.5 → 0.6

data/Rakefile

@@ -6,6 +6,8 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
 
+GEM_VERSION = '0.6'
+
 dbxml_dist = ENV['DBXML_DIST']
 if dbxml_dist
   puts "*** Using DBXML distribution in #{dbxml_dist}"
@@ -57,7 +59,6 @@ rd = Rake::RDocTask.new :rdoc do |rdoc|
   rdoc.rdoc_files.include 'rake/**/*task.rb'
 end
 
-GEM_VERSION = '0.5'
 GEM_FILES = rd.rdoc_files + FileList[
   'Rakefile',
   'ext/**/*.i',
@@ -71,9 +72,8 @@ spec = Gem::Specification.new do |s|
   s.version = GEM_VERSION
   s.date = Date.today.to_s
   s.authors = ["Steve Sloan"]
-  s.summary = 'Provides wrappers for the BDBXML (and BDB) C++ APIs, plus pure Ruby extensions'
-  s.description = <<-END
-  END
+  s.summary = 'Provides wrappers for the BDB XML C++ APIs, plus pure Ruby extensions'
+#  s.description =
   s.files = GEM_FILES.to_a.delete_if {|f| f.include?('.svn')}
   s.autorequire = 'rdbxml'
   s.test_files = Dir["test/test_*.rb"]

data/ext/dbxml_ruby.i

@@ -1,5 +1,7 @@
 %module dbxml
+%include "exception.i"
 %include "std_string.i"
+%include "std_except.i"
 
 %alias XmlManager::createQueryContext "create_query_context";
 
@@ -11,25 +13,66 @@
 %alias XmlDocument::getContent "content";
 %alias XmlDocument::setContent "content=";
 
-%alias XmlQueryContext::getNamespace "get_namespace";
-%alias XmlQueryContext::setNamespace "set_namespace";
-%alias XmlQueryContext::getDefaultCollection "default_collection";
-%alias XmlQueryContext::setDefaultCollection "default_collection=";
-%alias XmlQueryContext::getVariableValue "[]";
-%alias XmlQueryContext::setVariableValue "[]=";
+%alias XmlQueryContext::getNamespace "namespace";
+%alias XmlQueryContext::setNamespace "namespace=";
+%alias XmlQueryContext::getDefaultCollection "collection";
+%alias XmlQueryContext::setDefaultCollection "collection=";
 
 %alias XmlValue::asString "to_s";
 %alias XmlValue::asNumber "to_f";
 %alias XmlValue::asDocument "to_doc";
 
+%exceptionclass DbException;
+class DbException;
+
+%exceptionclass XmlException;
+%alias XmlException::what "to_s";
+%alias XmlException::getExceptionCode "err";
+
+class XmlException : public std::exception {
+public:
+  enum ExceptionCode {
+    INTERNAL_ERROR,  ///< An internal error occured.
+    CONTAINER_OPEN,  ///< The container is open.
+    CONTAINER_CLOSED,  ///< The container is closed.
+    NULL_POINTER,     ///< null pointer exception
+    INDEXER_PARSER_ERROR,  ///< XML Indexer could not parse a document.
+    DATABASE_ERROR,  ///< Berkeley DB reported a database problem.
+    XPATH_PARSER_ERROR,  ///< The XPath parser was unable to parse the XPath expression.
+    DOM_PARSER_ERROR,  ///< The DOM parser was unable to parse an XML document.
+    XPATH_EVALUATION_ERROR,  ///< The XPath evaluator was unable to execute the XPath expression.
+    NO_VARIABLE_BINDING,  ///< An XPath expression referred to variable without a value.
+    LAZY_EVALUATION,  ///< XmlResults is lazily evaluated.
+    DOCUMENT_NOT_FOUND,  ///< The specified document could not be found
+    CONTAINER_EXISTS,  ///< The container already exists.
+    UNKNOWN_INDEX,  ///< The indexing strategy name is unknown.
+    INVALID_VALUE, ///< An invalid parameter was passed.
+    VERSION_MISMATCH, ///< The container version and the dbxml library version are not compatible.
+    UNUSED_2,         ///< Placeholder
+    CONTAINER_NOT_FOUND, ///< The specified container could not be found
+    TRANSACTION_ERROR, ///< An XmlTransaction has already been committed or aborted
+    UNIQUE_ERROR, ///< A uniqueness constraint has been violated
+    NO_MEMORY_ERROR ///< An operation was unable to allocate memory
+  };
+
+  explicit XmlException(const DbException &e, const char *file = 0, int line = 0);
+  XmlException(const XmlException &);
+  virtual ~XmlException() throw();
+  virtual const char *what() const throw();
+
+  ExceptionCode getExceptionCode() const;
+  int getDbErrno() const;
+};
+
 %exception {
   try {
     $action
   } catch ( DbException &ex ) {
-    static VALUE rb_DBException = rb_define_class("DBException", rb_eStandardError);
-    rb_raise( rb_DBException, ex.what() );
-  } catch ( DbXml::XmlException &ex ) {
-    static VALUE rb_XmlException = rb_define_class("XmlException", rb_eStandardError);
-    rb_raise( rb_XmlException, ex.what() );
+    %raise( SWIG_NewPointerObj(new DbException(ex), SWIGTYPE_p_DbException, SWIG_POINTER_OWN),
+            "BDB Exception", SWIGTYPE_p_DbException );
+  } catch ( XmlException &ex ) {
+    %raise( SWIG_NewPointerObj(new XmlException(ex), SWIGTYPE_p_XmlException, SWIG_POINTER_OWN),
+            "BDB XXML Exception", SWIGTYPE_p_XmlException );
   }
 }
+

data/lib/rdbxml.rb

@@ -38,9 +38,18 @@ module RDBXML
   end
 end
 
+# Wraps and extends the XmlValue[http://www.sleepycat.com/xmldocs/api_cxx/XmlValue.html] class.
+# === Aliases:
+# to_s::   asString
+# to_f::   asNumber
+# to_doc:: asDocument (XmlDocument)
+# to_i::   #to_f
 class Dbxml::XmlValue
-  def to_i ;   self.to_f.to_i ; end
+  def to_i # :nodoc:
+    self.to_f.to_i
+  end
 
+  # Handles Numeric/Boolean/String comparisons
   def ==( that )
     if isNumber
       self.asNumber == that
@@ -52,33 +61,71 @@ class Dbxml::XmlValue
   end
 end
 
+# Wraps the XmlResults[http://www.sleepycat.com/xmldocs/api_cxx/XmlResults_list.html] class as an
+# enumerable collection of XmlValue or XmlDocument.
 class Dbxml::XmlResults
   include Enumerable
 
-  def each( &block )
+  # Iterates across each result (as an XmlValue) in the set
+  def each( &block ) # :yields: value
     self.reset
     while self.hasNext
       yield self.next
     end
   end
 
+  # Iterates across each result (as an XmlDocument) in the set
+  def each_doc( &block ) # :yields: document
+    self.reset
+    while self.hasNext
+      yield self.nextDocument
+    end
+  end
+
+  # Returns the first result as an XmlValue(or +nil+)
   def first
     self.reset
     self.hasNext ? self.next : nil
   end
 
+  # Returns the first result as an XmlDocument (or +nil+)
+  def first_doc
+    self.reset
+    self.hasNext ? self.nextDocument : nil
+  end
+
+  # Returns the result set as +newline+-joined strings
   def to_s
     collect { |v| v.to_s }.join "\n"
   end
 end
 
-class Dbxml::XmlDocument
-  @@namespaces = {}
+# Wraps and extends the XmlQueryContext[http://www.sleepycat.com/xmldocs/api_cxx/XmlQueryContext_list.html] class.
+# === Aliases
+# namespace::   getNamespace/setNamespace[http://www.sleepycat.com/xmldocs/api_cxx/XmlQueryContext_setNamespace.html]
+# collection::  getDefaultCollection/setDefaultCollection[http://www.sleepycat.com/xmldocs/api_cxx/XmlQueryContext_setDefaultCollection.html]
+class Dbxml::XmlQueryContext
+  # XmlQueryContext::getVariableValue[http://www.sleepycat.com/xmldocs/api_cxx/XmlQueryContext_setVariableValue.html]
+  def []( name )
+    getVariableValue name.to_s
+  end
+  # XmlQueryContext::setVariableValue[http://www.sleepycat.com/xmldocs/api_cxx/XmlQueryContext_setVariableValue.html]
+  def []=( name, val ) # :nodoc:
+    setVariableValue name.to_s, Dbxml::XmlValue.new(val)
+  end
+end
 
+# Wraps and extends the XmlDocument[http://www.sleepycat.com/xmldocs/api_cxx/XmlDocument_list.html] class.
+# === Aliases:
+# name:: getName/setName[http://www.sleepycat.com/xmldocs/api_cxx/XmlDocument_setName.html]
+# content:: getContent/setContent[http://www.sleepycat.com/xmldocs/api_cxx/XmlDocument_getContent.html]
+# to_s:: #content
+class Dbxml::XmlDocument
+  # Represents the document metadata as an Enumerable collection
   class MetaData
     include Enumerable
 
-    def initialize(doc)
+    def initialize(doc)  #:nodoc:
       @doc = doc
     end
 
@@ -92,7 +139,7 @@ class Dbxml::XmlDocument
       val = args.pop
       ns = args.shift || ''
       if val
-        @doc.setMetaData ns, name.to_s, XmlValue.new(val)
+        @doc.setMetaData ns, name.to_s, Dbxml::XmlValue.new(val)
       else
         delete name, ns
       end
@@ -103,7 +150,7 @@ class Dbxml::XmlDocument
       @doc.removeMetaData ns, name.to_s
     end
 
-    def each(&block)
+    def each(&block) # :yields: name, value, uri
       i = @doc.getMetaDataIterator
       while (xmd = i.next)
         yield xmd.get_name.to_sym, xmd.get_value, xmd.get_uri
@@ -118,12 +165,16 @@ class Dbxml::XmlDocument
     end
   end
 
+  # Returns the document metadata[http://www.sleepycat.com/xmldocs/api_cxx/XmlDocument_getMetaData.html]
   def meta
     @Meta ||= MetaData.new(self)
   end
 
 end
 
+# Wraps and extends the XmlContainer[http://www.sleepycat.com/xmldocs/api_cxx/XmlContainer_list.html] class.
+# === Aliases
+# manager:: getManager[http://www.sleepycat.com/xmldocs/api_cxx/XmlContainer_getManager.html]
 class Dbxml::XmlContainer
   include Enumerable
 
@@ -131,8 +182,8 @@ class Dbxml::XmlContainer
   def []( name )
     begin
       getDocument name.to_s
-    rescue XmlException => ex
-      raise unless ex.to_s =~ /document not found/i
+    rescue Dbxml::XmlException => ex
+      raise unless ex.err == XmlException::DOCUMENT_NOT_FOUND
       nil
     end
   end
@@ -152,32 +203,37 @@ class Dbxml::XmlContainer
     self << doc
   end
 
-  # Creates/updates the document +doc+.
+  # Creates/updates the XmlDocument +doc+.
   def <<( doc )
     ctx = getManager.createUpdateContext
     begin
       putDocument doc, ctx, 0
-    rescue XmlException => ex
-      raise unless ex.to_s =~ /document exists/i
+    rescue Dbxml::XmlException => ex
+      raise unless ex.err == XmlException::UNIQUE_ERROR
       d = self[doc.name]
       d.content = doc.content
       updateDocument d, ctx
     end
   end
 
-  # Iterates over each document in the collection
-  def each( &block )
+  # Iterates over each XmlDocument in the collection
+  def each( &block ) # :yields: document
     getAllDocuments.each(block)
   end
 end
 
+# Wraps and extends the XmlManager[http://www.sleepycat.com/xmldocs/api_cxx/XmlManager_list.html] class.
+# === Aliases
+# create_query_context:: createQueryContext
 class Dbxml::XmlManager
   # Opens the container named +name+, creating it if it doesn't exist.
   def []( name )
     openContainer name.to_s, Dbxml::DB_CREATE
   end
 
-  def query( xquery, opts = {}, &block )
+  # Runs the query +xquery+, creating a query context if necessary or using
+  # +opts[:ctx]+ if passed.
+  def query( xquery, opts = {}, &block ) # :yeilds: result
     opts[:ctx] ||= create_query_context
     q = self.prepare xquery, opts[:ctx]
     res = q.execute( opts[:ctx], 0 )
@@ -186,3 +242,12 @@ class Dbxml::XmlManager
     res
   end
 end
+
+# Wraps and extends the [http://www.sleepycat.com/xmldocs/api_cxx/env_class.html] class.
+class Db::DbEnv
+  # Convenience function to instantiate a XmlManager which attaches to
+  # this environment.
+  def manager
+    Dbxml::XmlManager.new self, 0
+  end
+end

data/test/test_rdbxml.rb

@@ -55,6 +55,20 @@ class XmlValueTest < Test::Unit::TestCase
   end
 end
 
+class XmlQueryContextTest < Test::Unit::TestCase
+  def setup
+    @db = RDBXML::XmlManager.new
+    @q = @db.create_query_context
+  end
+
+  def test_get_set_variable
+    @q[:foo] = 'xyz'
+    assert_equal 'xyz', @q[:foo].to_s
+    assert_equal 'xyz', @db.query('$foo', :ctx => @q).to_s
+  end
+
+end
+
 class XmlResultsTest < Test::Unit::TestCase
   def setup
     @db = RDBXML::XmlManager.new
@@ -93,8 +107,8 @@ class XmlDocumentTest < Test::Unit::TestCase
   def setup
     @dir = File.join( File.dirname(__FILE__), File.basename(__FILE__, '.rb') + '.db' )
     Dir.mkdir @dir  unless File.exists? @dir
-    @env = RDBXML::env(@dir)
-    @db = RDBXML::XmlManager.new @env, 0
+    @env = RDBXML::env @dir
+    @db = @env.manager
     @docs = @db['test']
   end
 

metadata

@@ -3,16 +3,16 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: rdbxml
 version: !ruby/object:Gem::Version 
-  version: "0.5"
-date: 2006-05-14 00:00:00 -07:00
-summary: Provides wrappers for the BDBXML (and BDB) C++ APIs, plus pure Ruby extensions
+  version: "0.6"
+date: 2006-05-29 00:00:00 -07:00
+summary: Provides wrappers for the BDB XML C++ APIs, plus pure Ruby extensions
 require_paths: 
 - lib
 - ext
 email: 
 homepage: 
 rubyforge_project: 
-description: ""
+description: 
 autorequire: rdbxml
 default_executable: 
 bindir: bin