Merge lp:~zorba-coders/zorba/couchbase_module-bug-1188063 into lp:zorba/couchbase-module

[Matthias Brantner]

renamed to zorba.io and adapted documentation

[Zorba Build Bot (zorba-buildbot)]

Validation queue starting for the following merge proposals:
https://code.launchpad.net/~zorba-coders/zorba/couchbase_module-bug-1188063/+merge/182781

Progress dashboard at http://jenkins.lambda.nu/view/ValidationQueue

[Matthias Brantner (matthias-brantner)]

review: Approve

[Zorba Build Bot (zorba-buildbot)]

Validation queue result for https://code.launchpad.net/~zorba-coders/zorba/couchbase_module-bug-1188063/+merge/182781

Stage "TestZorbaUbuntu" failed.
20 tests failed (8409 total tests run).

Check test results at http://jenkins.lambda.nu/job/TestZorbaUbuntu/253/testReport/ to view the results.

[Chris Hillery (ceejatec)]

This needs JSON validation too, correct?

[Chris Hillery (ceejatec)]

Per Matthias, validation is done in C++, so we can defer adding a JSON schema for now.

[Chris Hillery (ceejatec)]

Need to update error codes. Don't want to use CB0001 codes anymore.

review: Needs Fixing

Unmerged revisions

48. By Matthias Brantner on 2013-08-28

renamed and improved documentation

=== modified file 'src/couchbase.xq'
--- src/couchbase.xq	2013-08-09 09:37:05 +0000
+++ src/couchbase.xq	2013-08-28 23:18:04 +0000
@@ -1,7 +1,7 @@
-xquery version "3.0";
+jsoniq version "1.0";
 
 (:
- : Copyright 2012 The FLWOR Foundation.
+ : Copyright 2013 The FLWOR Foundation.
  :
  : Licensed under the Apache License, Version 2.0 (the "License");
  : you may not use this file except in compliance with the License.
@@ -19,9 +19,9 @@
 (:~
  : This module provides minimal functionality to interact with the
  : Couchbase NoSQL database.
- :
+ : <p/>
  : The module is built using the libcouchbase C client library and
- : exposes most of its functionality in XQuery with JSONiq extensions.
+ : exposes most of its functionality.
  : Beyond just allowing for basic key-value store operations (e.g.
  : put-/get-text or put-/get-binary, this module also allows to work
  : with Couchbase views in order to allow for complex JSON query
@@ -31,9 +31,8 @@
  : @project DB Drivers/Couchbase
  :
  :)
-module namespace cb = "http://www.zorba-xquery.com/modules/couchbase";
+module namespace cb = "http://zorba.io/modules/couchbase";
 
-declare namespace jn = "http://jsoniq.org/functions";
 declare namespace an = "http://zorba.io/annotations";
 
 declare namespace ver = "http://zorba.io/options/versioning";
@@ -55,11 +54,11 @@
  :)
 
 declare %an:sequential function cb:connect(
-  $host as xs:string, 
-  $username as xs:string?, 
-  $password as xs:string?, 
-  $bucket as xs:string)
-    as xs:anyURI
+  $host as string, 
+  $username as string?, 
+  $password as string?, 
+  $bucket as string)
+    as anyURI
 {
   cb:connect({"host" : $host, 
               "username" : $username,
@@ -71,13 +70,8 @@
  : Connect to the Couchbase server and return an opaque identifier
  : representing the established connection.
  :
- : @param $options a JSONiq object that contains the host, bucket,
- :   and user information.
- :
- : @option "host" endpoint of the Couchbase server (mandatory)
- : @option "username" username used for the connection (optional)
- : @option "password" password used for the connection (optional)
- : @option "bucket" name of an existing bucket (mandatory)
+ : @param $options an object that contains the host (mandatory),
+ :   bucket (mandatory), username, and password.
  :
  : @error cb:LCB0001 if the connection to the given host/bucket
  :   could not be established.
@@ -85,22 +79,12 @@
  : @error cb:CB0007 if a given option is not supported.
  :
  : @return an identifier for the established connection.
- :
- : Example:
- : <code>
- : {
- :   "host": "localhost:8091",
- :   "username" : null,
- :   "password" : null,
- :   "bucket" : "default"
- : }
- : </code>
  :)
-declare %an:sequential function cb:connect($options as object())
-    as xs:anyURI external;
+declare %an:sequential function cb:connect($options as object)
+    as anyURI external;
 
 (:~
- : Return the values of the given keys (type xs:string) as string.
+ : Return the values of the given keys as string.
  : 
  : @param $db connection reference
  : @param $key the requested keys
@@ -108,43 +92,39 @@
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  :
- : @return A sequence of string Items corresponding to the key
+ : @return A sequence of strings.
  :)
 
 declare %an:sequential function cb:get-text(
-  $db as xs:anyURI,
-  $key as xs:string*)
-as xs:string* external;
+  $db as anyURI,
+  $key as string*)
+as string* external;
 
 (:~
- : Return the values of the given keys (type xs:string) as string.
+ : Return the values of the given keys as string.
  : 
  : @param $db connection reference
  : @param $key the requested keys
- : @param $options JSONiq object with additional options
+ : @param $options an object specifying the expiration-time (integer)
+ :   or encoding (string; default is UTF-8).
  :
- : @option "expiration-time" xs:integer value for refreshing the expiration
- :   time in seconds. 
- : @option "encoding" string with the name of the encoding of the returned
- :   string (if not UTF-8).
- : 
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  : @error cb:CB0006 if the given encoding is not supported.
  : @error cb:CB0007 if any of the options is not supported.
- : @error cb:CB0009 if the given expiration time is not an xs:integer.
+ : @error cb:CB0009 if the given expiration time is not an integer.
  :
  : @return a sequence of strings for the given keys.
  :)
 
 declare %an:sequential function cb:get-text(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $options as object())
-as xs:string* external;
+  $db as anyURI,
+  $key as string*,
+  $options as object)
+as string* external;
 
 (:~
- : Return the values of the given keys (type xs:string) as base64Binary.
+ : Return the values of the given keys as base64Binary.
  : 
  : @param $db connection reference
  : @param $key the requested keys
@@ -152,91 +132,90 @@
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  :
- : @return a sequence of xs:base64Binary items for the given keys.
+ : @return a sequence of base64Binary items for the given keys.
  :)
 declare %an:sequential function cb:get-binary(
-  $db as xs:anyURI,
-  $key as xs:string*)
-as xs:base64Binary* external;
+  $db as anyURI,
+  $key as string*)
+as base64Binary* external;
 
 (:~
- : Return the values of the given keys (type xs:string) as base64Binary.
+ : Return the values of the given keys as base64Binary.
  : 
  : @param $db connection reference
  : @param $key the requested keys
- : @param $options JSONiq object with additional options
+ : @param $options an object with specyfing the expiration-time (integer).
  :
- : @option "expiration-time" xs:integer value for refreshing the expiration
- :   time in seconds. 
- : 
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  : @error cb:CB0007 if any of the options is not supported.
- : @error cb:CB0009 if the given expiration time is not an xs:integer.
+ : @error cb:CB0009 if the given expiration time is not an integer.
  :
- : @return a sequence of xs:base64Binary items for the given keys.
+ : @return a sequence of base64Binary items for the given keys.
  :)
 declare %an:sequential function cb:get-binary(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $options as object())
-as xs:base64Binary* external;
+  $db as anyURI,
+  $key as string*,
+  $options as object)
+as base64Binary* external;
 
 (:~
- : Remove the values matching the given keys (xs:string) from the server.
+ : Remove the values matching the given keys.
  :
  : @param $db connection reference
  : @param $key the keys of the values that should be removed.
  :
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
+ :
  : @return a empty sequence.
  :)
-declare %an:sequential function cb:remove($db as xs:anyURI, $key as xs:string*)
-    as empty-sequence() external;
+declare %an:sequential function cb:remove($db as anyURI, $key as string*)
+  as () external;
 
 (:~
  : Store the given key-value bindings.
- :
+ : <p/>
  : The values are stored with the UTF-8 encoding and a default
  : expiration time of 60 seconds.
  :
  : @param $db connection reference
  : @param $key the keys to store
- : @param $value the values (as xs:string) to be stored.
+ : @param $value the values to be stored.
  :
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  : @error cb:CB0005 if the number of keys doesn't match the number
  :   of values.
+ :
  : @return a empty sequence.
  :)  
 declare %an:sequential function cb:put-text(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $value as xs:string*)
-as empty-sequence()
+  $db as anyURI,
+  $key as string*,
+  $value as string*)
+  as ()
 {
   cb:put-text($db, $key, $value, { "expiration-time" : 60, "encoding" : "UTF-8" })
 };
 
 (:~
  : Store the given key-value bindings.
+ : <p/>
+ : Available options:
+ : <ul>
+ :   <li>"expiration-time" integer value that represent the : expiration time in seconds.</li>
+ :   <li>"operation" type of operation, possible values are : "add", "replace", "set", "append" and "prepend".</li>
+ :   <li>"encoding" the encoding that should be used for the : value (default is UTF-8).</li>
+ :   <li>"wait" variable for setting if a wait for persistancy in 
+ :       the storing key is needed, possible values are "persist" and "false".</li>
+ : </ul>
  :
  : @param $db connection reference
  : @param $key the keys to store
- : @param $value the values (as xs:string) to be stored.
- : @param $options JSONiq object with additional options
+ : @param $value the values (as string) to be stored.
+ : @param $options an object with additional options
  :
- : @option "expiration-time" integer value that represent the 
- :         expiration time in seconds.
- : @option "operation" type of operation, possible values are 
- :         "add", "replace", "set", "append" and "prepend".
- : @option "encoding" the encoding that should be used for the
- :         value (default is UTF-8).
- : @option "wait" variable for setting if a wait for persistancy in 
- :         the storing key is needed, possible values are "persist" 
- :         and "false".
  : 
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
@@ -244,24 +223,24 @@
  :   of values.
  : @error cb:CB0006 if the given encoding is not supported.
  : @error cb:CB0007 if any of the options is not supported.
- : @error cb:CB0009 if the given expiration time is not an xs:integer. 
+ : @error cb:CB0009 if the given expiration time is not an integer. 
  : @error cb:CB0011 if the stored Variable was not stored
  :
  : @return a empty sequence.
  :)  
 declare %an:sequential function cb:put-text(
-            $db as xs:anyURI,
-            $key as xs:string*,
-            $value as xs:string*,
-            $options as object())
-    as empty-sequence() external;
+            $db as anyURI,
+            $key as string*,
+            $value as string*,
+            $options as object)
+  as () external;
 
 (:~
  : Store the given key-value bindings.
  :
  : @param $db connection reference
  : @param $key the keys to store
- : @param $value the values (as xs:base64binary) to be stored.
+ : @param $value the values (as base64binary) to be stored.
  :
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
@@ -271,10 +250,10 @@
  : @return a empty sequence.
  :)  
 declare %an:sequential function cb:put-binary(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $value as xs:base64Binary*)
-as empty-sequence() 
+  $db as anyURI,
+  $key as string*,
+  $value as base64Binary*)
+  as () 
 {
   cb:put-binary($db, $key, $value, { "expiration-time" : 60 })
 };
@@ -284,8 +263,8 @@
  :
  : @param $db connection reference
  : @param $key the keys to store
- : @param $value the values (as xs:base64binary) to be stored.
- : @param $options JSONiq object with additional options
+ : @param $value the values (as base64binary) to be stored.
+ : @param $options an object with additional options
 
  : @option "expiration-time" integer value that represent the 
  :         expiration time in seconds.
@@ -300,17 +279,17 @@
  : @error cb:CB0005 if the number of keys doesn't match the number
  :   of values.
  : @error cb:CB0007 if any of the options is not supported.
- : @error cb:CB0009 if the given expiration time is not an xs:integer.
+ : @error cb:CB0009 if the given expiration time is not an integer.
  : @error cb:CB0011 if the stored Variable was not stored
  :
  : @return a empty sequence.
  :)  
 declare %an:sequential function cb:put-binary(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $value as xs:base64Binary*,
-  $options as object())
-as empty-sequence() external;
+  $db as anyURI,
+  $key as string*,
+  $value as base64Binary*,
+  $options as object)
+  as () external;
 
 
 (:~
@@ -323,8 +302,8 @@
  :
  : @return a empty sequence.
  :)
-declare %an:sequential function cb:flush($db as xs:anyURI)
-as empty-sequence() external;
+declare %an:sequential function cb:flush($db as anyURI)
+as () external;
 
 (:~
  : Refresh the expiration time of the given keys.
@@ -339,10 +318,10 @@
  : @return a empty sequence.
  :)
 declare %an:sequential function cb:touch(
-  $db as xs:anyURI,
-  $key as xs:string*,
-  $exp-time as xs:integer)
-as empty-sequence() external; 
+  $db as anyURI,
+  $key as string*,
+  $exp-time as integer)
+  as () external; 
 
 (:~
  : Retrieve the content of existing views.
@@ -356,14 +335,14 @@
  :
  : @return a sequence of strings (as JSON) containing information of the views.
  :)
-declare %an:sequential function cb:view($db as xs:anyURI, $path as xs:string*)
-  as object()*
+declare %an:sequential function cb:view($db as anyURI, $path as string*)
+  as object*
 {
   jn:parse-json(cb:view-text($db, $path))
 };
 
-declare %private %an:sequential function cb:view-text($db as xs:anyURI, $path as xs:string*)
-  as xs:string* external;
+declare %private %an:sequential function cb:view-text($db as anyURI, $path as string*)
+  as string* external;
 
 
 (:~
@@ -372,7 +351,7 @@
  : @param $db connection reference
  : @param $path contains the string of a view path 
  :        (e.g. "_design/test/_view/vies").
- : @param $options JSONiq object with additional options
+ : @param $options an object with additional options
  :
  : @option Json object whith options for the querying the view. available options:
  :         "encoding" string with the name of the encoding of the returned
@@ -394,24 +373,23 @@
  : @return a sequence of strings (as JSON) containing information of the views.
  :)
 declare %an:sequential function cb:view(
-  $db as xs:anyURI,
-  $path as xs:string*,
-  $options as object())
-as object()*
+  $db as anyURI,
+  $path as string*,
+  $options as object)
+  as object*
 {
   jn:parse-json(cb:view-text($db, $path, $options))
 };
 
 declare %private %an:sequential function cb:view-text(
-  $db as xs:anyURI,
-  $path as xs:string*,
-  $options as object())
-as xs:string* external; 
-
+  $db as anyURI,
+  $path as string*,
+  $options as object)
+  as string* external; 
 
 (:~
  : Create a document/view.
- 
+ : <p/>
  : If the document already exists, it is replaced. A document can hold several
  : views that must be specified in the same call of cb:create-view. 
  :
@@ -426,34 +404,31 @@
  :   created.
  :)
 declare %an:sequential function cb:create-view(
-  $db as xs:anyURI,
-  $doc-name as xs:string,
-  $view-names as xs:string*)
-as xs:string* external;
+  $db as anyURI,
+  $doc-name as string,
+  $view-names as string*)
+  as string* external;
 
 (:~
  : Create a document/view.
- 
- : If the document already exists, it is replaced. A document can hold several
+ : <p/>
+ : If the document already exists, it is replaced. A document can have several
  : views that must be specified in the same call of cb:create-view. 
+ : <p/>
+ : The following options can be specified:
+ : <ul>
+ :  <li>"key": name of the key displayed in the resulting object.</li>
+ :  <li>"values" a string or array of strings containing the values
+ :        that should be contained in the resulting object.</li>
+ :  <li>"function" the javascript map function of the view. If present,
+ :    the "key" and "values" options are ignored.</li>
+ : </ul>
  :
  : @param $db connection reference
  : @param $doc-name name of the document to create.
  : @param $view-names names of the views to create in the document.
  : @param $options options describing how to create the view.
  :
- : @option "key" value must be a string containing the name of the value
- :         in the json object stored in couchbase that is wanted to be 
- :         displayed as the value of "key" in the resulting json.
- : @option "values" value must be a string or an array of strings containing
- :         the name of the value in the json object stored in couchbase that 
- :         is wanted to be displayed as the value of "value" in the resulting
- :         json.
- : @option "function" string with a javascript function describing the 
- :         map function of the view. cb:create-view won't throw an error
- :         if the javascript function is not compilable or functional. If
- :         this option is set the "key" and "values" options are ignored.
- :
  : @error cb:LCB0002 if any error occurs in the communication with
  :   the server.
  : @error cb:CB0005 if the number of options doesn't match the number of
@@ -465,18 +440,17 @@
  :   created.
  :)
 declare %an:sequential function cb:create-view(
-  $db as xs:anyURI,
-  $doc-name as xs:string,
-  $view-names as xs:string*,
-  $options as object()*)
-as xs:string* external;
-
+  $db as anyURI,
+  $doc-name as string,
+  $view-names as string*,
+  $options as object*)
+  as string* external;
 
 (:~
  : Delete a document/view.
- 
+ : <p/>
  : If the document doesn't exists, function does nothing. All the views hold in the
- : Document are deleted, this function can't delete single views. 
+ : document are deleted, this function can't delete single views. 
  :
  : @param $db connection reference
  : @param $doc-name name of the document to create.
@@ -487,6 +461,6 @@
  : @return empty sequence.
  :)
 declare %an:sequential function cb:delete-view(
-  $db as xs:anyURI,
-  $doc as xs:string*)
-as xs:string* external;
+  $db as anyURI,
+  $doc as string*)
+  as string* external;

=== modified file 'src/couchbase.xq.src/couchbase.h'
--- src/couchbase.xq.src/couchbase.h	2013-01-21 22:42:49 +0000
+++ src/couchbase.xq.src/couchbase.h	2013-08-28 23:18:04 +0000
@@ -24,7 +24,7 @@
 #include <zorba/function.h>
 #include <zorba/dynamic_context.h>
 
-#define COUCHBASE_MODULE_NAMESPACE "http://www.zorba-xquery.com/modules/couchbase"
+#define COUCHBASE_MODULE_NAMESPACE "http://zorba.io/modules/couchbase"
 
 namespace zorba { namespace couchbase {