added documentation and fixes for cap

Doxygen/Examples.Durham/ensure-cap-constraint

@@ -0,0 +1,7 @@
+avocado> db.examples.ensureCapConstraint(10);
+{ "id" : "147879/934311", "type" : "cap", "size" : 10, "isNewlyCreated" : true }
+
+avocado> for (var i = 0;  i < 20;  ++i) { var d = db.examples.save( { n : i } ); }
+
+avocado> db.examples.count();
+10

Makefile.files

@@ -382,6 +382,7 @@ WIKI = \
 	HttpInterface \
 	HttpSimple \
 	HttpSystem \
+	IndexCap \
 	IndexGeo \
 	IndexHash \
 	IndexSkiplist \

Makefile.in

@@ -1024,6 +1024,7 @@ WIKI = \
 	HttpInterface \
 	HttpSimple \
 	HttpSystem \
+	IndexCap \
 	IndexGeo \
 	IndexHash \
 	IndexSkiplist \

RestServer/index-cap.dox

@@ -0,0 +1,76 @@
+////////////////////////////////////////////////////////////////////////////////
+/// @brief indexes
+///
+/// @file
+///
+/// DISCLAIMER
+///
+/// Copyright 2012 triagens GmbH, Cologne, Germany
+///
+/// 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.
+///
+/// Copyright holder is triAGENS GmbH, Cologne, Germany
+///
+/// @author Dr. Frank Celler
+/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @page IndexCapTOC
+///
+/// <ol>
+///  <li>@ref IndexCapHttp
+///   <ol>
+///    <li>@ref IndexCapHttpEnsureCap "POST /_api/index"</li>
+///   </ol>
+///  </li>
+///  <li>@ref IndexCapShell
+///   <ol>
+///    <li>@ref IndexCapShellEnsureCapConstraint "collection.ensureCapConstraint"</li>
+///   </ol>
+///  </li>
+/// </ol>
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @page IndexCap Cap Constraint
+///
+/// This is an introduction to AvocadoDB's size restrictions aka cap for
+/// collections.
+///
+/// <hr>
+/// @copydoc IndexCapTOC
+/// <hr>
+///
+/// It is possible to restrict the size of collection. If you add a document and
+/// the size exceeds the limit, then the least recently created or updated
+/// document will be dropped.
+///
+/// @section IndexCapHttp Accessing Cap Constraints via Http
+////////////////////////////////////////////////////////////
+///
+/// @anchor IndexCapHttpEnsureCap
+/// @copydetails JSF_POST_api_index_cap
+///
+/// @section IndexCapShell Accessing Cap Constraints from the Shell
+///////////////////////////////////////////////////////////////////
+///
+/// @anchor IndexCapShellEnsureGeoIndex
+/// @copydetails JS_EnsureCapConstraintVocbaseCol
+////////////////////////////////////////////////////////////////////////////////
+
+// Local Variables:
+// mode: c++
+// mode: outline-minor
+// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
+// End:

RestServer/otwp.dox

@@ -62,10 +62,7 @@
 ///    </li>
 ///    <li>@ref OTWPSimpleQueries
 ///     <ol>
-///      <li>@ref OTWPSimpleQueriesAll "PUT /_api/simple/all"</li>
 ///      <li>@ref OTWPSimpleQueriesByExample "PUT /_api/simple/by-example"</li>
-///      <li>@ref OTWPSimpleQueriesNear "PUT /_api/simple/near"</li>
-///      <li>@ref OTWPSimpleQueriesWithin "PUT /_api/simple/within"</li>
 ///     </ol>
 ///    </li>
 ///    <li>@ref Key-Value
@@ -96,14 +93,6 @@
 /// @copydetails JSA_PUT_api_simple_by_example
 /// <hr>
 ///
-/// @anchor OTWPSimpleQueriesNear
-/// @copydetails JSA_PUT_api_simple_near
-/// <hr>
-///
-/// @anchor OTWPSimpleQueriesWithin
-/// @copydetails JSA_PUT_api_simple_within
-/// <hr>
-///
 ////////////////////////////////////////////////////////////////////////////////
 
 // Local Variables:

RestServer/shell-index.dox

@@ -67,6 +67,7 @@
 /// - @ref IndexSkiplist
 /// - @ref IndexHash
 /// - @ref IndexPrioQueue
+/// - @ref IndexCap
 ///
 /// <hr>
 /// @copydoc ShellIndexTOC

V8/v8-vocbase.cpp

@@ -4329,8 +4329,9 @@ static v8::Handle<v8::Value> JS_DropIndexVocbaseCol (v8::Arguments const& argv)
 /// @FUN{@FA{collection}.ensureCapConstraint(@FA{size})}
 ///
 /// Creates a size restriction aka cap for the collection of @FA{size}.  If the
-/// restriction is in place and the @FA{size} plus one document is added to the
-/// collection, then last recently created or updated document is removed.
+/// restriction is in place and the (@FA{size} plus one) document is added to
+/// the collection, then the least recently created or updated document is
+/// removed.
 ///
 /// Note that at most one cap constraint is allowed per collection.
 ///
@@ -4342,7 +4343,7 @@ static v8::Handle<v8::Value> JS_DropIndexVocbaseCol (v8::Arguments const& argv)
 ///
 /// @EXAMPLES
 ///
-/// Restrict the number of document to at most 100 documents:
+/// Restrict the number of document to at most 10 documents:
 ///
 /// @verbinclude ensure-cap-constraint
 ////////////////////////////////////////////////////////////////////////////////

VocBase/simple-collection.c

@@ -1497,6 +1497,7 @@ static bool OpenIndexIterator (char const* filename, void* data) {
 
   if (iis != NULL && iis->_type == TRI_JSON_NUMBER) {
     iid = iis->_value._number;
+    TRI_UpdateTickVocBase(iid);
   }
   else {
     LOG_ERROR("ignoring index, index identifier could not be located");
@@ -2807,10 +2808,19 @@ static TRI_index_t* CreateCapConstraintSimCollection (TRI_sim_collection_t* sim,
   TRI_index_t* idx;
   bool ok;
 
+  if (created != NULL) {
+    *created = false;
+  }
+
   // check if we already know a cap constraint
   if (sim->base._capConstraint != NULL) {
-    TRI_set_errno(TRI_ERROR_AVOCADO_CAP_CONSTRAINT_ALREADY_DEFINED);
-    return NULL;
+    if (sim->base._capConstraint->_size == size) {
+      return &sim->base._capConstraint->base;
+    }
+    else {
+      TRI_set_errno(TRI_ERROR_AVOCADO_CAP_CONSTRAINT_ALREADY_DEFINED);
+      return NULL;
+    }
   }
 
   // create a new index
@@ -2881,9 +2891,14 @@ TRI_index_t* TRI_EnsureCapConstraintSimCollection (TRI_sim_collection_t* sim,
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
 
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -3793,9 +3808,14 @@ TRI_index_t* TRI_EnsureGeoIndex1SimCollection (TRI_sim_collection_t* sim,
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
 
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -3830,9 +3850,14 @@ TRI_index_t* TRI_EnsureGeoIndex2SimCollection (TRI_sim_collection_t* sim,
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
 
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }
 
 
@@ -3870,9 +3895,14 @@ TRI_index_t* TRI_EnsureHashIndexSimCollection(TRI_sim_collection_t* sim,
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
 
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }                                                
 
 
@@ -3910,9 +3940,14 @@ TRI_index_t* TRI_EnsurePriorityQueueIndexSimCollection(TRI_sim_collection_t* sim
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
 
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }                                                
 
 
@@ -3950,9 +3985,14 @@ TRI_index_t* TRI_EnsureSkiplistIndexSimCollection(TRI_sim_collection_t* sim,
   // outside write-lock
   // .............................................................................
 
-  res = TRI_SaveIndex(&sim->base, idx);
+  if (created) {
+    res = TRI_SaveIndex(&sim->base, idx);
   
-  return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+    return res == TRI_ERROR_NO_ERROR ? idx : NULL;
+  }
+  else {
+    return TRI_ERROR_NO_ERROR;
+  }
 }                                                
 
                                                 

VocBase/vocbase.c

@@ -521,6 +521,10 @@ static int ScanPath (TRI_vocbase_t* vocbase, char const* path) {
       // no need to lock as we are scanning
       res = TRI_LoadParameterInfoCollection(file, &info);
 
+      if (res == TRI_ERROR_NO_ERROR) {
+        TRI_UpdateTickVocBase(info._cid);
+      }
+
       if (res != TRI_ERROR_NO_ERROR) {
         LOG_DEBUG("ignoring directory '%s' without valid parameter file '%s'", file, TRI_COL_PARAMETER_FILE);
       }

js/common/tests/shell-cap-constraint.js

@@ -0,0 +1,174 @@
+/*jslint indent: 2,
+         nomen: true,
+         maxlen: 80 */
+/*global require,
+    db,
+    assertEqual, assertTrue,
+    print,
+    PRINT_OBJECT,
+    console,
+    AvocadoCollection, AvocadoEdgesCollection */
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test the cap constraint
+///
+/// @file
+///
+/// DISCLAIMER
+///
+/// Copyright 2010-2012 triagens GmbH, Cologne, Germany
+///
+/// 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.
+///
+/// Copyright holder is triAGENS GmbH, Cologne, Germany
+///
+/// @author Dr. Frank Celler, Lucas Dohmen
+/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
+////////////////////////////////////////////////////////////////////////////////
+
+var jsunity = require("jsunity");
+
+// -----------------------------------------------------------------------------
+// --SECTION--                                                     basic methods
+// -----------------------------------------------------------------------------
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test suite: Creation
+////////////////////////////////////////////////////////////////////////////////
+
+function CapConstraintSuite() {
+  var ERRORS = internal.errors;
+  var cn = "UnitTestsCollectionCap";
+  var collection = null;
+
+  return {
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief set up
+////////////////////////////////////////////////////////////////////////////////
+
+  setUp : function () {
+    internal.db._drop(cn);
+    collection = internal.db._create(cn, { waitForSync : false });
+  },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief tear down
+////////////////////////////////////////////////////////////////////////////////
+
+  tearDown : function () {
+    collection.drop();
+  },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test: cap creation
+////////////////////////////////////////////////////////////////////////////////
+
+    testCreationCap : function () {
+      var idx = collection.ensureCapConstraint(10);
+      var id = idx.id;
+
+      assertNotEqual(0, id);
+      assertEqual("cap", idx.type);
+      assertEqual(true, idx.isNewlyCreated);
+      assertEqual(10, idx.size);
+
+      idx = collection.ensureCapConstraint(10);
+
+      assertEqual(id, idx.id);
+      assertEqual("cap", idx.type);
+      assertEqual(false, idx.isNewlyCreated);
+      assertEqual(10, idx.size);
+    },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test: index creation error handling
+////////////////////////////////////////////////////////////////////////////////
+
+    testCreationTwoCap : function () {
+      var idx = collection.ensureCapConstraint(10);
+      var id = idx.id;
+
+      assertNotEqual(0, id);
+      assertEqual("cap", idx.type);
+      assertEqual(true, idx.isNewlyCreated);
+      assertEqual(10, idx.size);
+
+      try {
+        idx = collection.ensureCapConstraint(20);
+        fail();
+      }
+      catch (err) {
+        assertEqual(ERRORS.ERROR_AVOCADO_CAP_CONSTRAINT_ALREADY_DEFINED.code, err.errorNum);
+      }
+    },
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief test: number of documents
+////////////////////////////////////////////////////////////////////////////////
+
+    testNumberDocuments : function () {
+      var idx = collection.ensureCapConstraint(10);
+      var fun = function(d) { return d.n; };
+
+      assertEqual("cap", idx.type);
+      assertEqual(true, idx.isNewlyCreated);
+      assertEqual(10, idx.size);
+
+      assertEqual(0, collection.count());
+
+      for (var i = 0;  i < 10;  ++i) {
+        collection.save({ n : i });
+      }
+
+      assertEqual(10, collection.count());
+      assertEqual([0,1,2,3,4,5,6,7,8,9], collection.toArray().map(fun).sort());
+
+      collection.save({ n : 10 });
+      var a = collection.save({ n : 11 });
+
+      for (var i = 12;  i < 20;  ++i) {
+        collection.save({ n : i });
+      }
+
+      assertEqual(10, collection.count());
+      assertEqual([10,11,12,13,14,15,16,17,18,19], collection.toArray().map(fun).sort());
+
+      collection.replace(a._id, { n : 11, a : 1 });
+
+      for (var i = 20;  i < 29;  ++i) {
+        collection.save({ n : i });
+      }
+
+      assertEqual(10, collection.count());
+      assertEqual([11,20,21,22,23,24,25,26,27,28], collection.toArray().map(fun).sort());
+    }
+  };
+}
+
+// -----------------------------------------------------------------------------
+// --SECTION--                                                              main
+// -----------------------------------------------------------------------------
+
+////////////////////////////////////////////////////////////////////////////////
+/// @brief executes the test suites
+////////////////////////////////////////////////////////////////////////////////
+
+jsunity.run(CapConstraintSuite);
+
+return jsunity.done();
+
+// Local Variables:
+// mode: outline-minor
+// outline-regexp: "^\\(/// @brief\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @}\\)"
+// End: