sedna 0.1.0

data/CHANGES

@@ -0,0 +1,9 @@
+=== 0.1.0
+
+* Released on the December 8th, 2008.
+* Development preview (alpha) release.
+* Simple, high-level API.
+* Tested with Ruby 1.8.7 and Ruby 1.9.0.
+* Support for version 3.1 of the \Sedna XML DBMS.
+* Support for regular queries and transactions.
+* Support for auto-commit mode.

data/README

@@ -0,0 +1,86 @@
+= \Sedna XML database client library
+
+This library provides a Ruby client for <i>Sedna</i>, an open-source, native XML
+database system. The client is a Ruby extension that uses the official C
+driver that is shipped as part of the S<i></i>edna distribution.
+
+\Sedna provides a full range of core database services -- persistent storage,
+ACID transactions, security, indices, hot backup. Flexible XML processing
+facilities include W3C XQuery implementation, tight integration of XQuery with
+full-text search facilities and a node-level update language.
+
+For more information about the \Sedna XML database system, see the project page
+at http://modis.ispras.ru/sedna
+
+=== About the client library
+
+Author: Rolf Timmermans (r.timmermans <i>at</i> voormedia.com)
+
+Copyright 2008 Voormedia B.V.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+=== Current version
+
+The current version of this library is 0.1.0. This version is a <b>development
+preview</b>. The API may change significantly between minor versions.
+For a complete overview all recent and previous changes, see CHANGES.
+
+=== Requirements
+
+Before installing the \Sedna client library, make sure you have the library and
+header files of the C driver. They are shipped and installed as part of the binary
+distribution of \Sedna. When installing, choose either <tt>/usr/local/sedna</tt> or
+<tt>/opt/sedna</tt> as target locations.
+
+=== Installation
+
+After installing the \Sedna C driver (see above), simply install the Ruby client
+library as a rubygem.
+
+  % gem install sedna
+
+If the library or header files of the S<i></i>edna C driver are located at non-default
+locations, you can specify these locations by adding the <tt>--with-sedna-lib</tt>
+or <tt>--with-sedna-include</tt> options when installing.
+
+  % gem install sedna -- --with-sedna-lib=/path/to/sedna/lib --with-sedna-include=/path/to/sedna/include
+
+=== Usage
+
+After installation of the gem, +require+ the sedna library in order to start
+using it.
+
+  require 'rubygems'
+  require 'sedna'
+
+To start querying a database, create a new connection with the Sedna.connect
+method. When a block is given, the Sedna connection object will be returned
+which can be used to execute database statements.
+
+  connection_details = {
+    :database => "my_db",
+    :host => "localhost",
+    :username => "SYSTEM",
+    :password => "MANAGER",
+  }
+  Sedna.connect(connection_details) do |sedna|
+    # Start querying the database.
+    sedna.execute("create document 'mydoc'")                                  #=> nil
+    sedna.execute("update insert <msg>Hello world!</msg> into doc('mydoc')")  #=> nil
+    sedna.execute("doc('mydoc')/msg/text()")                                  #=> ["Hello world!"]
+    # The connection is closed automatically for us.
+  end
+
+See the documentation of the Sedna class -- the methods Sedna.connect and
+Sedna#execute in particular -- for more details.

data/ext/extconf.rb

@@ -0,0 +1,71 @@
+# Copyright 2008 Voormedia B.V.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Ruby extension library providing a client API to the Sedna native XML
+# database management system, based on the official Sedna C driver.
+
+# This file will generate a Makefile that can be used to build this extension.
+
+require "mkmf"
+
+if RUBY_VERSION < "1.8"
+  puts "This library requires ruby 1.8."
+  exit 1
+end
+
+driver = "/driver/c"
+default_driver_dirs = ["/usr/local/sedna#{driver}", "/opt/sedna#{driver}"]
+default_include_dirs = ["/usr/include", "/usr/include/sedna"] + default_driver_dirs
+default_lib_dirs = ["/usr/lib", "/usr/lib/sedna"] + default_driver_dirs
+idir, ldir = dir_config "sedna", nil, nil
+idir ||= default_include_dirs
+ldir ||= default_lib_dirs
+
+if not find_library "sedna", "SEconnect", *ldir
+  $stderr.write %{
+==============================================================================
+Could not find libsedna.
+* Did you install Sedna somewhere else than in /usr/local/sedna or /opt/sedna?
+  Call extconf.rb with --with-sedna-lib=/path to override default location.
+* Did you install a version of Sedna not compiled for your architecture?
+==============================================================================
+}
+  exit 2
+end
+
+if not find_header "libsedna.h", *idir or not find_header "sp_defs.h", *idir
+  $stderr.write %{
+==============================================================================
+Could not find header file(s) for libsedna.
+* Did you install Sedna somewhere else than in /usr/local/sedna or /opt/sedna?
+  Call extconf.rb with --with-sedna-include=/path to override default location.
+==============================================================================
+}
+  exit 3
+end
+
+if CONFIG["arch"] =~ /x86_64/i and File.exist?(f = $LIBPATH.first + File::Separator + "libsedna.a")
+  if system "/usr/bin/objdump --reloc \"#{f}\" 2>/dev/null | grep R_X86_64_32S >/dev/null && echo"
+    $stderr.write %{==============================================================================
+Library libsedna.a was statically compiled for a 64-bit platform as position-
+dependent code. It will not be possible to create a Ruby shared library with
+this Sedna library. Recompile the library as position-independent code by
+passing the -fPIC option to gcc.
+==============================================================================
+}
+    exit 4
+  end
+end
+
+create_makefile "sedna"

data/ext/sedna.c

@@ -0,0 +1,515 @@
+/*
+ * Copyright 2008 Voormedia B.V.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * Ruby extension library providing a client API to the Sedna native XML
+ * database management system, based on the official Sedna C driver.
+ *
+ * This file contains the Ruby C-extension.
+ */
+
+#include <string.h>
+#include "ruby.h"
+#include "libsedna.h"
+
+// Size of the read buffer.
+#define BUF_LEN 8192
+
+// Use macros to fool RDoc and hide some of our methods/aliases.
+#define rb_define_undocumented_alias(kl, new, old) rb_define_alias(kl, new, old)
+
+// Macro for verification of return values of the Sedna API + error handling.
+#define verify_res(expected, real, conn) if(real != expected) sedna_err(conn, real)
+
+// Macro for setting autocommit values on connection conn.
+#define sedna_autocommit_on(conn) sedna_autocommit(conn, SEDNA_AUTOCOMMIT_ON)
+#define sedna_autocommit_off(conn) sedna_autocommit(conn, SEDNA_AUTOCOMMIT_OFF)
+#define switch_sedna_autocommit(conn, val) if(val) sedna_autocommit_on(conn); else sedna_autocommit_off(conn)
+
+
+// Our classes.
+static VALUE cSedna;
+//static VALUE cSednaSet; //Unused so far.
+static VALUE cSednaException;
+static VALUE cSednaAuthError;
+static VALUE cSednaConnError;
+static VALUE cSednaTrnError;
+
+// Define a shorthand for the common SednaConnection structure.
+typedef struct SednaConnection SC;
+
+
+// Test the last error message for conn, and raise an exception if there is one.
+// The type of the exception is based on the result of the function that was
+// called that generated the error and should be passed as res.
+static void sedna_err(SC *conn, int res)
+{
+	VALUE exception;
+	const char *msg;
+	char *err, *details, *p;
+	switch(res) {
+		case SEDNA_AUTHENTICATION_FAILED:
+			exception = cSednaAuthError; break;
+		case SEDNA_OPEN_SESSION_FAILED:
+		case SEDNA_CLOSE_SESSION_FAILED:
+			exception = cSednaConnError; break;
+		case SEDNA_BEGIN_TRANSACTION_FAILED:
+		case SEDNA_ROLLBACK_TRANSACTION_FAILED:
+		case SEDNA_COMMIT_TRANSACTION_FAILED:
+			exception = cSednaTrnError; break;
+		case SEDNA_ERROR:
+		default:
+			exception = cSednaException;
+	}
+	msg = SEgetLastErrorMsg(conn);
+	err = strstr(msg, "\n");
+	details = strstr(err, "\nDetails: ");
+	if(err != NULL) {
+		err++;
+		if((p = strstr(err, "\n")) != NULL) strncpy(p, "\0", 1);
+	} else {
+		err = "Unknown error.";
+	}
+	if(details != NULL) {
+		details += 10;
+		if((p = strstr(details, "\n")) != NULL) strncpy(p, "\0", 1);
+		rb_raise(exception, "%s (%s)", err, details);
+	} else {
+		rb_raise(exception, "%s", err);
+	}
+}
+
+// Retrieve the SednaConnection struct from the Ruby Sedna object obj.
+static SC* sedna_struct(VALUE obj)
+{
+	SC *conn;
+	Data_Get_Struct(obj, SC, conn);
+	return conn;
+}
+
+// Close the Sedna connection and free memory of the SednaConnection struct.
+// Called at GC.
+static void sedna_free(SC *conn)
+{
+	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_CLOSED) SEclose(conn);
+	free(conn);
+}
+
+// Mark any references to other objects for Ruby GC (if any).
+static void sedna_mark(SC *conn)
+{ /* Unused. */ }
+
+// Read one record completely and return it as a Ruby String object.
+static VALUE sedna_read(SC *conn, int strip_n)
+{
+	int bytes_read = 0;
+	char buffer[BUF_LEN];
+	VALUE str = rb_str_buf_new(0);
+	do {
+		bytes_read = SEgetData(conn, buffer, BUF_LEN - 1);
+		if(bytes_read == SEDNA_ERROR) {
+			sedna_err(conn, SEDNA_ERROR);
+		} else {
+			if(bytes_read > 0) {
+				if(strip_n) {
+					// Strange bug adds newlines to beginning of every result
+					// except the first. Strip them! This a known issue in the
+					// network protocol and serialization mechanism.
+					// See: http://sourceforge.net/mailarchive/forum.php?thread_name=3034886f0812030132v3bbd8e2erd86480d3dc640664%40mail.gmail.com&forum_name=sedna-discussion
+					rb_str_buf_cat(str, buffer + 1, bytes_read - 1);
+					// Do not strip newlines from subsequent buffer reads.
+					strip_n = 0;
+				} else {
+					rb_str_buf_cat(str, buffer, bytes_read);
+				}
+			}
+		}
+	} while(bytes_read > 0);
+	return str;
+}
+
+// Iterate over all records and add them to a Ruby Array.
+static VALUE sedna_get_results(SC *conn)
+{
+	int res, strip_n = 0;
+	VALUE set = rb_ary_new();
+	while((res = SEnext(conn)) != SEDNA_RESULT_END) {
+		if(res == SEDNA_ERROR) sedna_err(conn, res);
+		// Set strip_n to 1 for all results except the first. This will cause
+		// sedna_read() an incorrect newline that is prepended to these results.
+		rb_ary_push(set, sedna_read(conn, strip_n));
+		if(!strip_n) strip_n = 1;
+	};
+	return set;
+}
+
+// Enable or disable autocommit.
+static void sedna_autocommit(SC *conn, int value)
+{
+	int res = SEsetConnectionAttr(conn, SEDNA_ATTR_AUTOCOMMIT, (void *)&value, sizeof(int));
+	verify_res(SEDNA_SET_ATTRIBUTE_SUCCEEDED, res, conn);
+}
+
+// Begin a transaction.
+static void sedna_tr_begin(SC *conn)
+{
+	int res = SEbegin(conn);
+	verify_res(SEDNA_BEGIN_TRANSACTION_SUCCEEDED, res, conn);
+}
+
+// Commit a transaction.
+static void sedna_tr_commit(SC *conn)
+{
+	int res = SEcommit(conn);
+	verify_res(SEDNA_COMMIT_TRANSACTION_SUCCEEDED, res, conn);
+}
+
+// Rollback a transaction.
+static void sedna_tr_rollback(SC *conn)
+{
+	int res = SErollback(conn);
+	verify_res(SEDNA_ROLLBACK_TRANSACTION_SUCCEEDED, res, conn);
+}
+
+// Alocates memory for a SednaConnection struct.
+static VALUE cSedna_s_new(VALUE klass)
+{
+	SC *conn, init = SEDNA_CONNECTION_INITIALIZER;
+	conn = (SC *)malloc(sizeof(SC));
+	if(conn == NULL) rb_raise(rb_eNoMemError, "Could not allocate memory.");
+	memcpy(conn, &init, sizeof(init));
+	return Data_Wrap_Struct(klass, sedna_mark, sedna_free, conn);
+}
+
+/* :nodoc:
+ *
+ * Initialize a new instance of Sedna.
+ */
+static VALUE cSedna_initialize(VALUE self, VALUE options)
+{
+	int res;
+	VALUE host_k, db_k, user_k, pw_k, host_v, db_v, user_v, pw_v;
+	char *host, *db, *user, *pw;
+	SC *conn = sedna_struct(self);
+
+	Check_Type(options, T_HASH);
+	host_k = ID2SYM(rb_intern("host"));
+	db_k = ID2SYM(rb_intern("database"));
+	user_k = ID2SYM(rb_intern("username"));
+	pw_k = ID2SYM(rb_intern("password"));
+
+	if(NIL_P(host_v = rb_hash_aref(options, host_k))) host = "localhost"; else host = STR2CSTR(host_v);
+	if(NIL_P(db_v = rb_hash_aref(options, db_k))) db = "test"; else db = STR2CSTR(db_v);
+	if(NIL_P(user_v = rb_hash_aref(options, user_k))) user = "SYSTEM"; else user = STR2CSTR(user_v);
+	if(NIL_P(pw_v = rb_hash_aref(options, pw_k))) pw = "MANAGER"; else pw = STR2CSTR(pw_v);
+
+	res = SEconnect(conn, host, db, user, pw);
+	verify_res(SEDNA_SESSION_OPEN, res, conn);
+
+	// Initialize @autocommit to true (default argument).
+	rb_iv_set(self, "@autocommit", Qtrue);
+
+	return self;
+}
+
+/*
+ * call-seq:
+ *   sedna.close -> nil
+ *
+ * Closes an open Sedna connection. If the connection was already closed when
+ * this method is called, nothing happens. A Sedna::ConnectionError is raised
+ * if the connection was open but could not be closed.
+ */
+static VALUE cSedna_close(VALUE self)
+{
+	int res;
+	SC *conn = sedna_struct(self);
+	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_CLOSED) {
+		res = SEclose(conn);
+		verify_res(SEDNA_SESSION_CLOSED, res, conn);
+	}
+	return Qnil;
+}
+
+/*
+ * call-seq:
+ *   Sedna.connect(details) -> Sedna instance
+ *   Sedna.connect(details) {|sedna| ... } -> nil
+ *
+ * Establishes a new connection to a \Sedna XML database. Accepts a hash that
+ * describes which database to \connect to.
+ *
+ * If a block is given, the block is executed if a connection was successfully
+ * established. The connection is closed at the end of the block. If called
+ * without a block, a Sedna object that represents the connection is returned.
+ * The connection should be closed by calling Sedna#close.
+ *
+ * If a connection cannot be initiated, a Sedna::ConnectionError is raised.
+ * If the authentication fails, a Sedna::AuthenticationError is raised.
+ *
+ * ==== Valid connection details keys
+ *
+ * * <tt>:host</tt> - Host name or IP address to which to \connect to (defaults to +localhost+).
+ * * <tt>:database</tt> - Name of the database to \connect to (defaults to +test+).
+ * * <tt>:username</tt> - User name to authenticate with (defaults to +SYSTEM+).
+ * * <tt>:password</tt> - Password to authenticate with (defaults to +MANAGER+).
+ *
+ * ==== Examples
+ *
+ * Call without a block and close the connection afterwards.
+ *   sedna = Sedna.connect(:database => "my_db", :host => "my_host")
+ *   # Query the database and close afterwards.
+ *   sedna.close
+ *
+ * Call with a block. The connection is closed automatically.
+ *   Sedna.connect(:database => "my_db", :host => "my_host") do |sedna|
+ *     # Query the database.
+ *     # The connection is closed automatically.
+ *   end
+ */
+static VALUE cSedna_s_connect(VALUE klass, VALUE options)
+{
+	int status;
+	VALUE obj = rb_funcall(klass, rb_intern("new"), 1, options);
+	if(rb_block_given_p()) {
+		rb_protect(rb_yield, obj, &status);
+		cSedna_close(obj);
+		if(status != 0) rb_jump_tag(status); // Re-raise any exception.
+		return Qnil;
+	} else {
+		return obj;
+	}
+}
+
+/*
+ * call-seq:
+ *   sedna.execute(query) -> array or nil
+ *   sedna.query(query) -> array or nil
+ *
+ * Execute the given +query+ against a \Sedna database. Returns an array if the
+ * given query is a select query. The elements of the array are strings that
+ * correspond to each result in the result set. If the query is an update query
+ * or a (bulk) load query, +nil+ is returned. When attempting to \execute a
+ * query on a closed connection, a Sedna::ConnectionError will be raised. A
+ * Sedna::Exception is raised if the query fails or is invalid.
+ *
+ * ==== Examples
+ *
+ * Create a new document.
+ *   sedna.execute "create document 'mydoc'"
+ *     #=> nil
+ * Update the newly created document with a root node.
+ *   sedna.execute "update insert <message>Hello world!</message> into doc('mydoc')"
+ *     #=> nil
+ * Select a node in a document using XPath.
+ *   sedna.execute "doc('mydoc')/message/text()"
+ *     #=> ["Hello world!"]
+ *
+ * ==== Further reading
+ *
+ * For more information about \Sedna's database query syntax and support, see the
+ * <i>Database language</i> section of the official documentation of the
+ * \Sedna project at http://modis.ispras.ru/sedna/progguide/ProgGuidese2.html
+ */
+static VALUE cSedna_execute(VALUE self, VALUE query)
+{
+	int res;
+	SC *conn = sedna_struct(self);
+	if(SEconnectionStatus(conn) != SEDNA_CONNECTION_OK) rb_raise(cSednaConnError, "Connection is closed.");
+	res = SEexecute(conn, STR2CSTR(query));
+	switch(res) {
+		case SEDNA_QUERY_SUCCEEDED:
+			return sedna_get_results(conn);
+		case SEDNA_UPDATE_SUCCEEDED:
+		case SEDNA_BULK_LOAD_SUCCEEDED:
+			return Qnil;
+		default:
+			sedna_err(conn, res);
+			return Qnil;
+	}
+}
+
+/* :nodoc:
+ *
+ * Turn autocommit on or off.
+ */
+static VALUE cSedna_autocommit_set(VALUE self, VALUE auto_commit)
+{
+	int val = (RTEST(auto_commit) ? Qtrue : Qfalse);
+	SC *conn = sedna_struct(self);
+	switch_sedna_autocommit(conn, val);
+	rb_iv_set(self, "@autocommit", val);
+	return Qnil;
+}
+
+/* :nodoc:
+ *
+ * Get the current autocommit value.
+ */
+static VALUE cSedna_autocommit_get(VALUE self)
+{
+	return rb_iv_get(self, "@autocommit");
+}
+
+/*
+ * call-seq:
+ *   sedna.transaction { ... } -> true
+ *
+ * Wraps the given block in a \transaction. If the block runs
+ * completely, the \transaction is committed. If the stack is unwinded
+ * prematurely, the \transaction is rolled back. This typically happens
+ * when an \Exception is raised by calling +raise+ or a Symbol is thrown by
+ * invoking +throw+. Note that Exceptions will not be rescued -- they will be
+ * re-raised after rolling back the \transaction.
+ *
+ * This method returns +true+ if the \transaction is successfully committed
+ * to the database. If the given block completes successfully, but the
+ * \transaction fails to be committed, a Sedna::TransactionError will
+ * be raised. 
+ *
+ * ==== Examples
+ *
+ *   sedna.transaction do
+ *     count = sedna.execute "count(collection('mycol')/items)"  #=> 0
+ *     sedna.execute "update insert <total>#{count}</total> into doc('mydoc')"
+ *     # ...
+ *   end
+ *   # Transaction is committed.
+ *
+ *   sedna.transaction do
+ *     count = sedna.execute "count(collection('mycol')/items)"  #=> 0
+ *     throw :no_items if count == 0
+ *     # ... never get here
+ *   end
+ *   # Transaction is rolled back.
+ */
+static VALUE cSedna_transaction(VALUE self)
+{
+	int status;
+	SC *conn = sedna_struct(self);
+	sedna_autocommit_off(conn);
+	sedna_tr_begin(conn);
+	rb_protect(rb_yield, Qnil, &status);
+	if(status == 0) {
+		// Attempt to commit.
+		if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) sedna_tr_commit(conn);
+		else rb_raise(cSednaTrnError, "The transaction was prematurely ended, but no error was encountered. Did you rescue an exception inside the transaction?");
+		switch_sedna_autocommit(conn, rb_iv_get(self, "@autocommit"));
+	} else {
+		// Stack has unwinded, attempt to roll back.
+		if(SEtransactionStatus(conn) == SEDNA_TRANSACTION_ACTIVE) sedna_tr_rollback(conn);
+		switch_sedna_autocommit(conn, rb_iv_get(self, "@autocommit"));
+		rb_jump_tag(status); // Re-raise exception.
+	}
+	return Qtrue;
+}
+
+void Init_sedna()
+{
+	/*
+	 * Objects of class Sedna represent a connection to a \Sedna XML
+	 * database. Establish a new connection by invoking the Sedna.connect
+	 * class method.
+	 *
+	 *   connection_details = {
+	 *     :database => "my_db",
+	 *     :host => "localhost",
+	 *     :username => "SYSTEM",
+	 *     :password => "MANAGER",
+	 *   }
+	 *   Sedna.connect(connection_details) do |sedna|
+	 *     # Query the database.
+	 *     # The connection is closed automatically.
+	 *   end
+	 *
+	 * See the README for a high-level overview of how to use this library.
+	 */
+	cSedna = rb_define_class("Sedna", rb_cObject);
+	rb_define_alloc_func(cSedna, cSedna_s_new);
+	rb_define_singleton_method(cSedna, "connect", cSedna_s_connect, 1);
+	rb_define_method(cSedna, "initialize", cSedna_initialize, 1);
+	rb_define_method(cSedna, "execute", cSedna_execute, 1);
+	rb_define_undocumented_alias(cSedna, "query", "execute");
+	rb_define_method(cSedna, "close", cSedna_close, 0);
+
+	/*
+	 * Document-attr: autocommit
+	 *
+	 * When autocommit is set to +true+ (default), database queries can be run
+	 * without explicitly wrapping them in a transaction. Each query that is not
+	 * part of a \transaction is automatically committed to the database.
+	 * Explicit transactions in auto-commit mode will still be committed
+	 * atomically.
+	 * 
+	 * When autocommit is set to +false+, queries can only be run inside an
+	 * explicit transaction. Queries run outside transactions will fail with a
+	 * Sedna::Exception.
+	 */
+	/* Trick RDoc into thinking this is a regular attribute. We documented the
+	 * attribute above.
+	rb_define_attr(cSedna, "autocommit", 1, 1);
+	 */
+	rb_define_method(cSedna, "autocommit=", cSedna_autocommit_set, 1);
+	rb_define_method(cSedna, "autocommit", cSedna_autocommit_get, 0);
+	rb_define_method(cSedna, "transaction", cSedna_transaction, 0);
+
+	/*
+	 * The result set of a database query.
+	 */
+	// Unused so far...
+	//cSednaSet = rb_define_class_under(cSedna, "Set", rb_cArray);
+
+	/*
+	 * Generic exception class for errors. All errors raised by the \Sedna
+	 * client library are of type Sedna::Exception.
+	 *
+	 * === Subclasses
+	 *
+	 * For some specific errors, an exception of a particular subtype is raised.
+	 *
+	 * [Sedna::AuthenticationError]
+	 *   Raised when a database connection was successfully established, but
+	 *   the supplied credentials were incorrect. Can only be raised when
+	 *   invoking Sedna.connect.
+	 * [Sedna::ConnectionError]
+	 *   Raised when a connection to a database could not be established or when
+	 *   a connection could not be closed. Can be raised when invoking Sedna.connect
+	 *   or Sedna#close.
+	 * [Sedna::TransactionError]
+	 *   Raised when a transaction could not be committed.
+	 */
+	cSednaException = rb_define_class_under(cSedna, "Exception", rb_eStandardError);
+
+	/*
+	 * Sedna::AuthenticationError is a subclass of Sedna::Exception, and is
+	 * raised when a database connection was successfully established, but the
+	 * supplied credentials were incorrect. Can only be raised when invoking
+	 * Sedna.connect.
+	 */
+	cSednaAuthError = rb_define_class_under(cSedna, "AuthenticationError", cSednaException);
+
+	/*
+	 * Sedna::ConnectionError is a subclass of Sedna::Exception, and is
+	 * raised when a connection to a database could not be established or when
+	 * a connection could not be closed. Can be raised when invoking Sedna.connect
+	 * or Sedna#close.
+	 */
+	cSednaConnError = rb_define_class_under(cSedna, "ConnectionError", cSednaException);
+
+	/*
+	 * Sedna::TransactionError is a subclass of Sedna::Exception, and is
+	 * raised when a transaction could not be committed.
+	 */
+	cSednaTrnError = rb_define_class_under(cSedna, "TransactionError", cSednaException);
+}

data/test/test_sedna.rb

@@ -0,0 +1,387 @@
+#!/usr/bin/env ruby
+
+# Copyright 2008 Voormedia B.V.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#     http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Ruby extension library providing a client API to the Sedna native XML
+# database management system, based on the official Sedna C driver.
+
+# This file contains the test suite to verify the client library is working
+# correctly.
+
+require 'test/unit'
+require '../ext/sedna'
+require 'socket'
+
+class TestSedna < Test::Unit::TestCase
+  def setup
+    @connection = {
+      :database => "test",
+      :host => "localhost",
+      :username => "SYSTEM",
+      :password => "MANAGER",
+    }
+  end
+  
+  def teardown
+  end
+  
+  def test_aaa_connection
+    port = 5050
+    begin
+      s = TCPSocket.new @connection[:host], port
+    rescue Errno::ECONNREFUSED, SocketError
+      # No DB appears to be running; fail fatally. Do not run the other tests and just exit.
+      puts "Connection to port #{port} on #{@connection[:host]} could not be established. Check if the Sedna XML database is running before running this test suite."
+      exit 1
+    end
+    assert s
+    s.close
+  end
+  
+  # Test Sedna.connect.
+  def test_connect_should_return_sedna_object
+    sedna = Sedna.connect @connection
+    assert_kind_of Sedna, sedna
+    sedna.close
+  end
+
+  def test_connect_should_raise_exception_when_host_not_found
+    assert_raises Sedna::ConnectionError do
+      Sedna.connect @connection.merge(:host => "non-existant-host")
+    end
+  end
+
+  def test_connect_should_raise_exception_when_credentials_are_incorrect
+    assert_raises Sedna::AuthenticationError do
+      Sedna.connect @connection.merge(:username => "non-existant-user")
+    end
+  end
+  
+  def test_connect_should_return_nil_on_error
+    begin
+      sedna = Sedna.connect @connection.merge(:username => "non-existant-user")
+    rescue
+    end
+    assert_nil sedna
+  end
+  
+  def test_connect_should_return_nil_if_block_given
+    sedna = Sedna.connect @connection do |s| end
+    assert_nil sedna
+  end
+  
+  def test_connect_should_close_connection_after_block
+    sedna = nil
+    Sedna.connect @connection do |s|
+      sedna = s
+    end
+    assert_raises Sedna::ConnectionError do
+      sedna.execute "<test/>"
+    end
+  end
+  
+  def test_connect_should_close_connection_if_exception_is_raised_inside_block
+    sedna = nil
+    begin
+      Sedna.connect @connection do |s|
+        sedna = s
+        raise Exception
+      end
+    rescue Exception
+    end
+    assert_raises Sedna::ConnectionError do
+      sedna.execute "<test/>"
+    end
+  end
+  
+  def test_connect_should_close_connection_if_something_is_thrown_inside_block
+    sedna = nil
+    catch :ball do
+      Sedna.connect @connection do |s|
+        sedna = s
+        throw :ball
+      end
+    end
+    assert_raises Sedna::ConnectionError do
+      sedna.execute "<test/>"
+    end
+  end
+  
+  def test_connect_should_reraise_exceptions_from_inside_block
+    assert_raises Exception do
+      Sedna.connect @connection do
+        raise Exception
+      end
+    end
+  end
+
+  # TODO: Fix the following strangely-failing test case.
+  #def test_zzz_connect_should_not_fail_to_close_connection_when_require_called_inside_block
+  #  # Squash a strange bug -- only appears to work if this test is run last and nothing else fails.
+  #  assert_nothing_raised do
+  #    Sedna.connect @connection do |sedna|
+  #      require 'pp'
+  #    end
+  #  end
+  #end
+  
+  # Test sedna.close.
+  def test_close_should_return_nil
+    sedna = Sedna.connect @connection
+    assert_nil sedna.close
+  end
+
+  def test_close_should_fail_silently_if_connection_is_already_closed
+    sedna = Sedna.connect @connection
+    assert_nothing_raised do
+      sedna.close
+      sedna.close
+    end
+  end
+  
+  # Test sedna.execute / sedna.query.
+  def test_execute_should_return_nil_for_data_structure_query
+    Sedna.connect @connection do |sedna|
+      name = "test_execute_should_return_nil_for_create_document_query"
+      sedna.execute("drop document '#{name}'") rescue Sedna::Exception
+      assert_nil sedna.execute("create document '#{name}'")
+      sedna.execute("drop document '#{name}'") rescue Sedna::Exception
+    end
+  end
+  
+  def test_execute_should_return_array_for_select_query
+    Sedna.connect @connection do |sedna|
+      assert_kind_of Array, sedna.execute("<test/>")
+    end
+  end
+  
+  def test_execute_should_return_array_with_single_string_for_single_select_query
+    Sedna.connect @connection do |sedna|
+      assert_equal ["<test/>"], sedna.execute("<test/>")
+    end
+  end
+  
+  def test_execute_should_return_array_with_strings_for_select_query
+    Sedna.connect @connection do |sedna|
+      assert_equal ["<test/>", "<test/>", "<test/>"], sedna.execute("<test/>, <test/>, <test/>")
+    end
+  end
+
+  def test_execute_should_fail_if_autocommit_is_false
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = false
+      assert_raises Sedna::Exception do
+        sedna.execute "<test/>"
+      end
+    end
+  end
+  
+  def test_execute_should_fail_with_sedna_exception_for_invalid_statments
+    Sedna.connect @connection do |sedna|
+      assert_raises Sedna::Exception do
+        sedna.execute "INVALID"
+      end
+    end
+  end
+  
+  def test_execute_should_fail_with_sedna_connection_error_if_connection_is_closed
+    Sedna.connect @connection do |sedna|
+      sedna.close
+      assert_raises Sedna::ConnectionError do
+        sedna.execute "<test/>"
+      end
+    end
+  end
+  
+  def test_execute_should_strip_first_newline_of_all_but_first_results
+    Sedna.connect @connection do |sedna|
+      name = "test_execute_should_strip_first_newline_of_all_but_first_results"
+      sedna.execute("drop document '#{name}'") rescue Sedna::Exception
+      sedna.execute("create document '#{name}'")
+      sedna.execute("update insert <test><a>\n\nt</a><a>\n\nt</a><a>\n\nt</a></test> into doc('#{name}')")
+      assert_equal ["\n\nt", "\n\nt", "\n\nt"], sedna.execute("doc('#{name}')/test/a/text()")
+      sedna.execute("drop document '#{name}'") rescue Sedna::Exception
+    end
+  end
+  
+  def test_query_should_be_alias_of_execute
+    Sedna.connect @connection do |sedna|
+      assert_equal ["<test/>"], sedna.query("<test/>")
+    end
+  end
+  
+  # Test sedna.autocommit= / sedna.autocommit.
+  def test_autocommit_should_return_true_by_default
+    Sedna.connect @connection do |sedna|
+      assert_equal true, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_return_true_if_set_to_true
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = true
+      assert_equal true, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_return_false_if_set_to_false
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = false
+      assert_equal false, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_return_true_if_set_to_true_after_being_set_to_false
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = false
+      sedna.autocommit = true
+      assert_equal true, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_return_true_if_argument_evaluates_to_true
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = "string evaluates to true"
+      assert_equal true, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_return_false_if_argument_evaluates_to_false
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = nil
+      assert_equal false, sedna.autocommit
+    end
+  end
+  
+  def test_autocommit_should_be_reenabled_after_transactions
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = true
+      sedna.transaction do end
+      assert_nothing_raised do
+        sedna.execute "<test/>"
+      end
+    end
+  end
+  
+  # Test sedna.transaction.
+  def test_transaction_should_return_true_if_committed
+    Sedna.connect @connection do |sedna|
+      assert_equal true, sedna.transaction(){}
+    end
+  end
+  
+  def test_transaction_should_raise_localjumperror_if_no_block_is_given
+    assert_raises LocalJumpError do
+      Sedna.connect @connection do |sedna|
+        sedna.transaction
+      end
+    end
+  end
+  
+  def test_transaction_should_be_possible_with_autocommit
+    Sedna.connect @connection do |sedna|
+      sedna.autocommit = true
+      assert_nothing_raised do
+        sedna.transaction do end
+      end
+    end
+  end
+  
+  def test_transaction_should_fail_with_transaction_error_if_another_transaction_is_started_inside_it
+    assert_raises Sedna::TransactionError do
+      Sedna.connect @connection do |sedna|
+        sedna.transaction do
+          sedna.transaction do end
+        end
+      end
+    end
+  end
+  
+  def test_transaction_should_commit_if_block_given
+    Sedna.connect @connection do |sedna|
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+      sedna.execute "create document '#{name}'"
+      sedna.transaction do
+        sedna.execute "update insert <test>test</test> into doc('#{name}')"
+      end
+      assert_equal 1, sedna.execute("count(doc('#{name}')/test)").first.to_i
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+    end
+  end
+
+  def test_transaction_should_rollback_if_exception_is_raised_inside_block
+    Sedna.connect @connection do |sedna|
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+      sedna.execute "create document '#{name}'"
+      begin
+        sedna.transaction do
+          sedna.execute "update insert <test>test</test> into doc('#{name}')"
+          raise Exception
+        end
+      rescue Exception
+      end
+      assert_equal 0, sedna.execute("count(doc('#{name}')/test)").first.to_i
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+    end
+  end
+
+  def test_transaction_should_rollback_if_something_is_thrown_inside_block
+    Sedna.connect @connection do |sedna|
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+      sedna.execute "create document '#{name}'"
+      catch :ball do
+        sedna.transaction do
+          sedna.execute "update insert <test>test</test> into doc('#{name}')"
+          throw :ball
+        end
+      end
+      assert_equal 0, sedna.execute("count(doc('#{name}')/test)").first.to_i
+      sedna.execute "drop document '#{name}'" rescue Sedna::Exception
+    end
+  end
+
+  def test_transaction_should_raise_transaction_error_if_invalid_statement_caused_exception_but_it_was_rescued
+    assert_raises Sedna::TransactionError do
+      Sedna.connect @connection do |sedna|
+        sedna.transaction do
+          sedna.execute "FAILS" rescue Sedna::Exception
+        end
+      end
+    end
+  end
+  
+  def test_transaction_should_reraise_exceptions_from_inside_block
+    Sedna.connect @connection do |sedna|
+      assert_raises Exception do
+        sedna.transaction do
+          raise Exception
+        end
+      end
+    end
+  end
+
+  def test_transaction_with_invalid_statements_should_cause_transaction_to_roll_back_once
+    exc = nil
+    begin
+      Sedna.connect @connection do |sedna|
+        sedna.transaction do
+          sedna.execute "FAILS"
+        end
+      end
+    rescue Sedna::Exception => exc
+    end
+    assert_equal "It is a dynamic error if evaluation of an expression relies on some part of the dynamic context that has not been assigned a value.", exc.message
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: sedna
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Rolf Timmermans
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-08 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Ruby extension that provides a client library for the Sedna XML DBMS, making use of the official C driver of the Sedna project.
+email: r.timmermans@voormedia.com
+executables: []
+
+extensions: 
+- ext/extconf.rb
+extra_rdoc_files: 
+- CHANGES
+- README
+- ext/sedna.c
+files: 
+- ext/extconf.rb
+- ext/sedna.c
+- test/test_sedna.rb
+- CHANGES
+- README
+has_rdoc: true
+homepage: http://sedna.rubyforge.org/
+post_install_message: 
+rdoc_options: 
+- --title
+- Sedna XML DBMS client library for Ruby
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: 
+- Sedna XML DBMS C driver (library and headers).
+rubyforge_project: sedna
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Sedna XML DBMS client library.
+test_files: 
+- test/test_sedna.rb