issue #245

CHANGELOG

@@ -36,6 +36,8 @@ v1.1.beta1 (2012-XX-XX)
 
 * issue #246: added clear() function in arangosh
 
+* issue #245: Documentation: Central place for naming rules/limits inside ArangoDB
+
 * reduced size of hash index elements by 50 %, allowing more index elements to fit in 
   memory
 

Documentation/Makefile.files

@@ -75,6 +75,7 @@ WIKI = \
 	JSModuleInternal \
 	JSModules \
 	Key-Value \
+	NamingConventions \
 	RefManual \
 	RestDocument \
 	RestEdge \

arangod/Ahuacatl/ahuacatl-ast-node.c

@@ -381,8 +381,19 @@ TRI_aql_node_t* TRI_CreateNodeCollectionAql (TRI_aql_context_t* const context,
   
   if (strlen(name) == 0) {
     TRI_SetErrorContextAql(context, TRI_ERROR_QUERY_COLLECTION_NOT_FOUND, name);
+
     return NULL;
   }
+  else {
+    TRI_col_parameter_t parameters;
+
+    parameters._isSystem = true;
+    if (! TRI_IsAllowedCollectionName(&parameters, name)) {
+      TRI_SetErrorContextAql(context, TRI_ERROR_ARANGO_ILLEGAL_NAME, name);
+
+      return NULL;
+    }
+  }
 
   {
     TRI_aql_collection_hint_t* hint;

arangod/Documentation/aql.dox

@@ -322,10 +322,8 @@
 /// happens to have the same name as a keyword, the name must be enclosed in
 /// backticks.
 ///
-/// Allowed characters in collection names are the letters @LIT{a} to @LIT{z} 
-/// (both in lower and upper case) and the numbers @LIT{0} to @LIT{9} and the
-/// the underscore (@LIT{_}) symbol. A collection name must start with either
-/// a letter or a number, but not with an underscore.
+/// Please refer to the @ref NamingConventions about collection name naming
+/// conventions. 
 ///
 /// @subsubsection AqlAttributeNames Attribute names
 /// 
@@ -334,6 +332,9 @@
 /// collections with ambiguous attribute names might be used in a query.
 /// To avoid any ambiguity, it is not allowed to refer to an unqualified 
 /// attribute name.
+///
+/// Please refer to the @ref NamingConventions for more information about the
+/// attribute naming conventions.
 /// 
 /// @EXAMPLE{aqlattributenamesvalid,active user with active friends}
 ///

arangod/Documentation/implementor-manual.dox

@@ -45,6 +45,7 @@
 ///  <li>@ref HttpBatch</li>
 ///  <li>@ref HttpImport</li>
 ///  <li>@ref Communication</li>
+///  <li>@ref NamingConventions</li>
 ///  <li>@ref ArangoErrors</li>
 ///  <li>@ref Glossary</li>
 /// </ul>
@@ -78,6 +79,7 @@
 ///  <li>Advanced Topics
 ///   <ul>
 ///    <li>@ref Communication</li>
+///    <li>@ref NamingConventions</li>
 ///    <li>@ref ArangoErrors</li>
 ///   </ul>
 ///  </li>

arangod/Documentation/names.dox

@@ -0,0 +1,99 @@
+////////////////////////////////////////////////////////////////////////////////
+/// @brief naming conventions in ArangoDB
+///
+/// @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 Jan Steemann
+/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
+////////////////////////////////////////////////////////////////////////////////
+
+////////////////////////////////////////////////////////////////////////////////
+/// @page NamingConventions Naming Conventions in ArangoDB
+///
+/// The following naming conventions should be followed by users when creating
+/// collections and documents in ArangoDB.
+///
+/// @section CollectionNames Collection names
+///
+/// Users can pick names for their collections as desired, provided the following
+/// naming constraints are not violated: 
+///
+/// - Collection names must only consist of the letters @LIT{a} to @LIT{z} 
+///   (both in lower and upper case), the numbers @LIT{0} to @LIT{9}, the
+///   the underscore (@LIT{_}), or the dash (@LIT{-}) symbol. This also means that
+///   any non-ASCII collection names are not allowed.
+///
+/// - Regular collection names must start with either a letter or a number, and not
+///   with the underscore or the dash symbol. Collection names starting with
+///   either an underscore or a dash are considered to be system collections that
+///   are for ArangoDB's internal use only. System collection names should not be
+///   used by end users for their own collections.
+///
+/// - The maximum allowed length of a collection name is 64 bytes.
+///
+/// - Collection names are case-sensitive.
+///
+/// @section AttributeNames Attribute names 
+///
+/// Users can pick attribute names for document keys as desired, provided the
+/// following attribute naming constraints are not violated:
+///
+/// - Attribute names starting with an underscore are considered to be system
+///   attributes for ArangoDB's internal use. Such attribute names are already used
+///   by ArangoDB for special purposes, e.g. @LIT{_id} is used to contain a
+///   document's id, @LIT{_rev} is used to contain the revision number, and the
+///   @LIT{_from} and @LIT{_to} attributes are used within edge collections.
+///   More system attributes may be added in the future without further notice
+///   so end users should not use attribute names starting with an underscore
+///   for their own attributes.
+///
+/// - Attribute names should not start with the at-mark (@LIT{@}). The at-mark
+///   at the start of attribute names is reserved in ArangoDB for future use cases.
+///
+/// - Theoretically, attribute names can include punctuation and special characters
+///   as desired, provided the name is a valid UTF-8 string. 
+///   For maximum portability, special characters should be avoided though. 
+///   For example, attribute names may
+///   contain the dot symbol, but the dot has a special meaning in Javascript and
+///   also in AQL, so when using such attribute names in one of these languages, the
+///   attribute name would need to be quoted by the end user. This will work but
+///   requires more work so it might be better to use attribute names which don't
+///   require any quoting/escaping in all languages used. This includes languages
+///   used by the client (e.g. Ruby, PHP) if the attributes are mapped to object
+///   members there.
+///
+/// - ArangoDB does not enforce a length limit for attribute names. However, long
+///   attribute names may use more memory in result sets etc. Therefore the use
+///   of long attribute names is discouraged.
+///
+/// - As ArangoDB saves document attribute names separate from the actual document
+///   attribute value data, the combined length of all attribute names for a document 
+///   must fit into an ArangoDB shape structure. The maximum combined names length
+///   is variable and depends on the number and data types of attributes used.
+///
+/// - Attribute names are case-sensitive.
+////////////////////////////////////////////////////////////////////////////////
+
+// Local Variables:
+// mode: c++
+// mode: outline-minor
+// outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)"
+// End:

arangod/VocBase/vocbase.c

@@ -674,21 +674,12 @@ static TRI_vocbase_col_t* BearCollectionVocBase (TRI_vocbase_t* vocbase,
   union { void const* v; TRI_vocbase_col_t* c; } found;
   TRI_vocbase_col_t* collection;
   TRI_col_parameter_t parameter;
-  char wrong;
-  
-  if (*name == '\0') {
-    TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
-    return NULL;
-  }
   
   // check that the name does not contain any strange characters
   parameter._isSystem = false;
-  wrong = TRI_IsAllowedCollectionName(&parameter, name);
-
-  if (wrong != 0) {
-    LOG_DEBUG("found illegal character in name: %c", wrong);
-
+  if (! TRI_IsAllowedCollectionName(&parameter, name)) {
     TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
+
     return NULL;
   }
 
@@ -1003,12 +994,13 @@ size_t PageSize;
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief checks if a collection name is allowed
 ///
-/// Returns 0 for success or the offending character.
+/// Returns true if the name is allowed and false otherwise
 ////////////////////////////////////////////////////////////////////////////////
 
-char TRI_IsAllowedCollectionName (TRI_col_parameter_t* paramater, char const* name) {
+bool TRI_IsAllowedCollectionName (TRI_col_parameter_t* paramater, char const* name) {
   bool ok;
   char const* ptr;
+  size_t length = 0;
 
   for (ptr = name;  *ptr;  ++ptr) {
     if (name < ptr || paramater->_isSystem) {
@@ -1019,11 +1011,18 @@ char TRI_IsAllowedCollectionName (TRI_col_parameter_t* paramater, char const* na
     }
 
     if (! ok) {
-      return *ptr;
+      return false;
     }
+
+    ++length;
   }
 
-  return 0;
+  if (length == 0 || length > 64) {
+    // invalid name length
+    return false;
+  } 
+
+  return true;
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -1411,24 +1410,15 @@ TRI_vocbase_col_t* TRI_CreateCollectionVocBase (TRI_vocbase_t* vocbase,
   TRI_document_collection_t* sim;
   TRI_col_type_e type;
   char const* name;
-  char wrong;
   void const* found;
   
   assert(parameter);
   name = parameter->_name;
 
-  if (*name == '\0') {
-    TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
-    return NULL;
-  }
-  
   // check that the name does not contain any strange characters
-  wrong = TRI_IsAllowedCollectionName(parameter, name);
-
-  if (wrong != 0) {
-    LOG_DEBUG("found illegal character in name: %c", wrong);
-
+  if (! TRI_IsAllowedCollectionName(parameter, name)) {
     TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
+
     return NULL;
   }
   
@@ -1695,7 +1685,6 @@ int TRI_RenameCollectionVocBase (TRI_vocbase_t* vocbase, TRI_vocbase_col_t* coll
   TRI_col_info_t info;
   TRI_col_parameter_t parameter;
   void const* found;
-  char wrong;
   char const* oldName;
   int res;
 
@@ -1706,16 +1695,8 @@ int TRI_RenameCollectionVocBase (TRI_vocbase_t* vocbase, TRI_vocbase_col_t* coll
     return TRI_ERROR_NO_ERROR;
   }
 
-  // check name conventions
-  if (*newName == '\0') {
-    return TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
-  }
-
   parameter._isSystem = (*oldName == '_');
-  wrong = TRI_IsAllowedCollectionName(&parameter, newName);
-
-  if (wrong != 0) {
-    LOG_DEBUG("found illegal character in name: %c", wrong);
+  if (! TRI_IsAllowedCollectionName(&parameter, newName)) {
     return TRI_set_errno(TRI_ERROR_ARANGO_ILLEGAL_NAME);
   }
 

arangod/VocBase/vocbase.h

@@ -445,7 +445,7 @@ TRI_vocbase_col_t;
 /// @brief checks if a collection is allowed
 ////////////////////////////////////////////////////////////////////////////////
 
-char TRI_IsAllowedCollectionName (struct TRI_col_parameter_s*, char const*);
+bool TRI_IsAllowedCollectionName (struct TRI_col_parameter_s*, char const*);
 
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief create a new tick

js/common/bootstrap/errors.js

@@ -58,7 +58,7 @@
     "ERROR_ARANGO_COLLECTION_NOT_FOUND" : { "code" : 1203, "message" : "collection not found" }, 
     "ERROR_ARANGO_COLLECTION_PARAMETER_MISSING" : { "code" : 1204, "message" : "parameter 'collection' not found" }, 
     "ERROR_ARANGO_DOCUMENT_HANDLE_BAD" : { "code" : 1205, "message" : "illegal document handle" }, 
-    "ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL" : { "code" : 1206, "message" : "maixaml size of journal too small" }, 
+    "ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL" : { "code" : 1206, "message" : "maixmal size of journal too small" }, 
     "ERROR_ARANGO_DUPLICATE_NAME"  : { "code" : 1207, "message" : "duplicate name" }, 
     "ERROR_ARANGO_ILLEGAL_NAME"    : { "code" : 1208, "message" : "illegal name" }, 
     "ERROR_ARANGO_NO_INDEX"        : { "code" : 1209, "message" : "no suitable index known" }, 

lib/BasicsC/errors.dat

@@ -76,7 +76,7 @@ ERROR_ARANGO_DOCUMENT_NOT_FOUND,1202,"document not found","Will be raised when a
 ERROR_ARANGO_COLLECTION_NOT_FOUND,1203,"collection not found","Will be raised when a collection with a given identifier or name is unknown."
 ERROR_ARANGO_COLLECTION_PARAMETER_MISSING,1204,"parameter 'collection' not found","Will be raised when the collection parameter is missing."
 ERROR_ARANGO_DOCUMENT_HANDLE_BAD,1205,"illegal document handle","Will be raised when a document handle is corrupt."
-ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL,1206,"maixaml size of journal too small","Will be raised when the maximal size of the journal is too small."
+ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL,1206,"maixmal size of journal too small","Will be raised when the maximal size of the journal is too small."
 ERROR_ARANGO_DUPLICATE_NAME,1207,"duplicate name","Will be raised when a name duplicate is detected."
 ERROR_ARANGO_ILLEGAL_NAME,1208,"illegal name","Will be raised when an illegal name is detected."
 ERROR_ARANGO_NO_INDEX,1209,"no suitable index known","Will be raised when no suitable index for the query is known."

lib/BasicsC/voc-errors.c

@@ -54,7 +54,7 @@ void TRI_InitialiseErrorMessages (void) {
   REG_ERROR(ERROR_ARANGO_COLLECTION_NOT_FOUND, "collection not found");
   REG_ERROR(ERROR_ARANGO_COLLECTION_PARAMETER_MISSING, "parameter 'collection' not found");
   REG_ERROR(ERROR_ARANGO_DOCUMENT_HANDLE_BAD, "illegal document handle");
-  REG_ERROR(ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL, "maixaml size of journal too small");
+  REG_ERROR(ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL, "maixmal size of journal too small");
   REG_ERROR(ERROR_ARANGO_DUPLICATE_NAME, "duplicate name");
   REG_ERROR(ERROR_ARANGO_ILLEGAL_NAME, "illegal name");
   REG_ERROR(ERROR_ARANGO_NO_INDEX, "no suitable index known");

lib/BasicsC/voc-errors.h

@@ -107,7 +107,7 @@ extern "C" {
 ///   Will be raised when the collection parameter is missing.
 /// - 1205: @CODE{illegal document handle}
 ///   Will be raised when a document handle is corrupt.
-/// - 1206: @CODE{maixaml size of journal too small}
+/// - 1206: @CODE{maixmal size of journal too small}
 ///   Will be raised when the maximal size of the journal is too small.
 /// - 1207: @CODE{duplicate name}
 ///   Will be raised when a name duplicate is detected.
@@ -761,7 +761,7 @@ void TRI_InitialiseErrorMessages (void);
 ////////////////////////////////////////////////////////////////////////////////
 /// @brief 1206: ERROR_ARANGO_MAXIMAL_SIZE_TOO_SMALL
 ///
-/// maixaml size of journal too small
+/// maixmal size of journal too small
 ///
 /// Will be raised when the maximal size of the journal is too small.
 ////////////////////////////////////////////////////////////////////////////////