merged master with upstream

CHANGES_NEXT_RELEASE

@@ -1,5 +0,0 @@
-- Add: CORS Preflight Requests support for all NGSIv2 resources, -corsMaxAge switch (#501)
-- Fix: null not working in q/mq filter in subscriptions (#2998)
-- Fix: case-sensitive header duplication (e.g. "Content-Type" and "Content-type") in custom notifications (#2893)
-- Fix: bug in GTE and LTE operations in query filters (q/mq), both for GET operations and subscriptions (#2995)
-- Fix: Wrong "max one service-path allowed for subscriptions" in NGSIv2 subscription operation (#2948)

README.md

@@ -169,7 +169,7 @@ Orion Context Broker is licensed under Affero General Public License (GPL) versi
 
 ## Support
 
-Ask your thorough programmming questions using [stackoverflow](http://stackoverflow.com/questions/ask)
+Ask your thorough programming questions using [stackoverflow](http://stackoverflow.com/questions/ask)
 and your general questions on [FIWARE Q&A](https://ask.fiware.org). In both cases please use the tag `fiware-orion`
 
 [Top](#top)

doc/apiary/v2/fiware-ngsiv2-reference.apib

@@ -615,7 +615,7 @@ might be useful in understanding the format.
 The Simple Query Language provides a simplified syntax to retrieve entities which match a set of
 conditions.
 A query is composed by a list of statements separated by the ';' character.
-Each statement express a matching condition.
+Each statement expresses a matching condition.
 The query returns all the entities that match all the matching conditions (AND logical operator). 
 
 There are two kinds of statements: *unary statements* and *binary statements*.
@@ -667,7 +667,7 @@ The list of operators (and the format of the values they use) is as follows:
       entities with an attribute named `color` but whose value is `white` do not match.
     + A range, specified as a minimum and a maximum, separated by `..`, e.g. `temperature==10..20`.
       For an entity to match, it must contain the *target property* (temperature),
-      and the *target property value* must be in the interval between the minimum and maximum
+      and the *target property value* must be between the upper and lower limits
       of the range (both included). Ranges can only be used with *target properties* that represent
       dates (in ISO8601 format), numbers or strings.
 + **Unequal**: `!=`. This operator accepts the following types of right-hand side:
@@ -681,7 +681,7 @@ The list of operators (and the format of the values they use) is as follows:
       attribute `color` is set to `white` will match.
     + A range, specified as a minimum and maximum separated by `..`, e.g. `temperature!=10..20`.
       For an entity to match, it must contain the *target property* (temperature) and the
-      *target property value* must **not** be in the interval between the minimum and the maximum
+      *target property value* must **not** be between the upper and lower limits
       (both included). Ranges can only be used with elements *target properties* that represent dates
       (in ISO8601 format), numbers or strings.
 + **Greater than**: `>`. The right-hand side must be a single element, e.g. `temperature>42`.
@@ -712,7 +712,7 @@ The list of operators (and the format of the values they use) is as follows:
 
 The symbol `:` can be used instead of `==`.
 
-In the case of equal or unequal, if s string to match includes a `,`, you can use simple quote
+In case of equal or unequal, if the string to match includes a `,`, you can use single quote
 (`'`) to disable the special meaning of the comma,  e.g: `color=='light,green','deep,blue'`.
 The first example would match a color with the exact value 'light,green' OR 'deep,blue'. The
 simple quote syntax can be also used to force string interpretation in filters, e.g.
@@ -1032,20 +1032,20 @@ Response code:
 + Parameters
     + id: Boe_Idearium (optional, string) - A comma-separated list of elements.
       Retrieve entities whose ID matches one of the elements in the list.
-      Incompatible with idPattern.
+      Incompatible with `idPattern`.
 
     + type: Room (optional, string) -  comma-separated list of elements.
       Retrieve entities whose type matches one of the elements in the list.
       Incompatible with `typePattern`.
 
     + idPattern: Bode_.* (optional, string) - A correctly formated regular expression.
-      Retrieve entities whose ID matches the regular expression. Incompatible with id.
+      Retrieve entities whose ID matches the regular expression. Incompatible with `id`.
 
     + typePattern: Room_.* (optional, string) - A correctly formated regular expression.
       Retrieve entities whose type matches the regular expression. Incompatible with `type`.
 
     + q: temperature>40 (optional, string) - A query expression, composed of a list of statements
-      separated by `;`, i.e., q=statement;statements;statement.
+      separated by `;`, i.e., q=statement1;statement2;statement3.
       See [Simple Query Language specification](#simple_query_language). 
 
     + mq: temperature.accuracy<0.9 (optional, string) - A query expression for attribute metadata,
@@ -1258,7 +1258,7 @@ Response:
 
 + Parameters
     + entityId (required, string) - Id of the entity to be retrieved
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
     + attrs: temperature,humidity (optional, string) - Comma-separated list of attribute names whose
       data are to be included in the response. The attributes are retrieved in the order specified
@@ -1398,7 +1398,7 @@ Response:
 
 + Parameters 
     + entityId (required, string) - Id of the entity in question.
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
     + options (optional, string) - Operations options
         + Members
@@ -1430,7 +1430,7 @@ Response:
 
 + Parameters 
     + entityId (required, string) - Id of the entity to be deleted
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
 
 + Response 204
@@ -1453,7 +1453,7 @@ Response:
 
 + Parameters
     + entityId: Bcn_Welt (required, string) - Id of the entity
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
     + attrName: temperature (required, string) - Name of the attribute to be retrieved.
     + metadata: accuracy (optional, string) - A list of metadata names to include in the response.
@@ -1511,7 +1511,7 @@ Response:
 
 + Parameters
     + entityId: Bcn_Welt (required, string) - Id of the entity.
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
     entities with the same entity id.
     + attrName: temperature (required, string) - Attribute name.
 
@@ -1529,7 +1529,7 @@ This operation returns the `value` property with the value of the attribute.
 * If attribute value is JSON Array or Object:
   * If `Accept` header can be expanded to `application/json` or `text/plain` return the value as a JSON with a
     response type of application/json or text/plain (whichever is the first in `Accept` header or
-    `application/json` in the case of `Accept: */*`).
+    `application/json` in case of `Accept: */*`).
   * Else return a HTTP error "406 Not Acceptable: accepted MIME types: application/json, text/plain"
 * If attribute value is a string, number, null or boolean:
   * If `Accept` header can be expanded to text/plain return the value as text. In case of a string, citation
@@ -1544,7 +1544,7 @@ Response:
 
 + Parameters
     + entityId: Bcn_Welt (required, string) - Id of the entity in question
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
     + attrName: address (required, string) - Name of the attribute to be retrieved.
 
@@ -1583,7 +1583,7 @@ Response:
 
 + Parameters
     + entityId: Bcn_Welt (required, string) - Id of the entity to be updated.
-    + type (optional, string) - Entity type, to avoid ambiguity in the case there are several
+    + type (optional, string) - Entity type, to avoid ambiguity in case there are several
       entities with the same entity id.
     + attrName: address (required, string) - Attribute name.
 
@@ -1731,7 +1731,7 @@ A `subject` contains the following subfields:
 
 + `entities`: A list of objects, each one composed of the following subfields:
   + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same
-     time, but at least one of them must be present.
+     time, but one of them must be present.
   + `type` or `typePattern`: Type or type pattern of the affected entities. Both cannot be used at
      the same time. If omitted, it means "any entity type".
 + `condition`: Condition to trigger notifications. This field is optional and it may contain two
@@ -2043,7 +2043,7 @@ The `dataProvided` field contains the following subfields:
 
 + `entities`: A list of objects, each one composed of the following subfields:
     + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same
-      time, but at least one of them must be present.
+      time, but one of them must be present.
     + `type` or `typePattern`: Type or pattern of the affected entities. Both cannot be used at
       the same time. If omitted, it means "any entity type".
 + `attrs`: List of attributes to be provided (if not specified, all attributes).
@@ -2312,7 +2312,7 @@ The payload may contain the following elements (all of them optional):
 + `entities`: a list of entites to search for. Each element is represented by a JSON object with the
   following elements:
     + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same
-      time, but at least one of them must be present.
+      time, but one of them must be present.
     + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at
       the same time. If omitted, it means "any entity type".
 + `attributes`: a list of attribute names to search for. If omitted, it means "all attributes".
@@ -2417,12 +2417,12 @@ operation. The payload is an object with two properties:
 
 + `actionType`, to specify the kind of register action to do: either CREATE, UPDATE, or DELETE.
 + `registrations`, an array of registrations, each one specified using the JSON registration 
-  representation format (described above). In the case of CREATE operation, the registration `id`
+  representation format (described above). In case of CREATE operation, the registration `id`
   must not be included.
 
 Response:
 
-* Successful operation uses 200 OK. In addition, in the case of successful CREATE, a list of IDs is
+* Successful operation uses 200 OK. In addition, in case of successful CREATE, a list of IDs is
   returned, each one corresponding to the ID of the element in the request payload and in that same
   order.
 * Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for
@@ -2482,7 +2482,7 @@ The payload may contain the following elements (all of them optional):
 + `entities`: a list of entites to search for. Each entity is represented by a JSON object with the
   following elements:
     + `id` or `idPattern`: Id or pattern of the affected entities. Both cannot be used at the same
-      time, but at least one of them must be present.
+      time, but one of them must be present.
     + `type` or `typePattern`: Type or type pattern of the entities to search for. Both cannot be used at
       the same time. If omitted, it means "any entity type".
 + `attributes`: a list of attribute names to search for. If omitted, it means "all attributes".

doc/apiary/v2/fiware-ngsiv2-reference.errata

@@ -1,49 +0,0 @@
-o Line 564 (## Simple Query Language):
-    Change:
-      Each statement express a matching condition.
-    For
-      Each statement expresses a matching condition.
-
-o There are several occurences of "Both cannot be used at the same time, but at least one of them must be present". It has been suggested
-  as alternative wording:
-  - "Both cannot be used at the same time, but one of them must be present"
-  - "Mandatory and mutually exclusive" (more concise)
-
-o Line 922 (### List entities):
-  Incompatible with idPattern ->  Incompatible with `idPattern`.
-
-o Line 932 (### List entities)
-  Incompatible with type -> Incompatible with `type`.
-
-o Line 660 (## Simple Query Language):
-    Change:
-      you can use simple quote
-    For
-      you can use single quote
-
-o Line 661 (## Simple Query Language):
-    Change:
-       In the case of equal or unequal
-    For
-       In case of equal or unequal
-    (An overall search for "case" in the whole document could help to detect other cases)
-
-o Line 661 (## Simple Query Language):
-    Change:
-       if s string
-    For
-       if the string
-
-o General in ## Simple Query Language:
-    Change:
-      its value must be in the interval between the minimum and maximum of the range
-    For
-      its value must be between the upper and lower limits of the range (Ken's)
-      or
-      its value must be between the upper and lower bounds of the range (Cantera's)
-
-o ## List Entities
-    Change:
-      q=statement;statements;statement
-    For
-      q=statement1;statement2;statement3 (aligned with mq=)

doc/manuals/admin/README.md

@@ -10,13 +10,18 @@ Orion Context Broker: Installation & Administration Manual.
 * [Running Orion as system service](running.md)
 * [Running Orion from command line](cli.md)
 * [Database administration](database_admin.md)
+* [Data model](database_model.md)
 * [Logs](logs.md)
 * [Watchdog](watchdog.md)
 * [Rush relayer](rush.md)
 * [Management REST inferface](management_api.md)
 * [Metrics API](metrics_api.md)
 * [Statistics](statistics.md)
 * [Performance Tuning](perf_tuning.md)
-* [Data model](database_model.md)
+* [Upgrading from previous to 0.14.1](upgrading_crossing_0-14-1.md)
+* [Upgrading from previous to 0.19.0](upgrading_crossing_0-19-0.md)
+* [Upgrading from previous to 0.21.0](admin/upgrading_crossing_0-21-0.md)
+* [Upgrading from previous to 1.3.0](admin/upgrading_crossing_1-3-0.md)
+* [Upgrading from previous to 1.5.0](admin/upgrading_crossing_1-5-0.md)
 * [Sanity check procedures](sanity_check.md)
 * [Diagnosis procedures](diagnosis.md)

doc/manuals/admin/build_source.md

@@ -30,7 +30,7 @@ commands that require root privilege):
 
         sudo yum install boost-devel libcurl-devel gnutls-devel libgcrypt-devel openssl-devel libuuid-devel
 
-* Install the Mongo Driver from source:
+* Install the Mongo Driver from source. The following procedure corresponds with default installation, if you want to include SASL and SSL support use [this alternative procedure](#building-mongodb-driver-with-sasl-and-ssl-support) instead.
 
         wget https://github.com/mongodb/mongo-cxx-driver/archive/legacy-1.1.2.tar.gz
         tar xfvz legacy-1.1.2.tar.gz
@@ -131,6 +131,18 @@ You can generate the RPM for the source code (optional):
 
 * The generated RPMs are placed in directory `~/rpmbuild/RPMS/x86_64`.
 
+### Building MongoDB driver with SASL and SSL support
+
+The procedure is as follows:
+
+```
+wget https://github.com/mongodb/mongo-cxx-driver/archive/legacy-1.1.2.tar.gz
+tar xfvz legacy-1.1.2.tar.gz cd mongo-cxx-driver-legacy-1.1.2
+yum install cyrus-sasl-devel
+scons --use-sasl-client --ssl                                   # The build/linux2/normal/libmongoclient.a library is generated as outcome
+sudo scons install --prefix=/usr/local --use-sasl-client --ssl  # This puts .h files in /usr/local/include/mongo and libmongoclient.a in /usr/local/lib
+```
+
 ## Others
 
 If you have build orion in a system different from CentOS 6.x, don't hesitate to tell us and contribute to expand this section. Probably the best way if doing a pull request to modify this file with the new information. Thanks!

doc/manuals/admin/cli.md

@@ -116,9 +116,10 @@ The list of available options is the following:
 -   **-cprForwardLimit**. Maximum number of forwarded requests to Context Providers for a single client request
     (default is no limit). Use 0 to disable Context Providers forwarding completely.
 -   **-corsOrigin <domain>**. Enables Cross-Origin Resource Sharing,
-    specifing the allowed origin (use `__ALL` for `*`). Detailed information on CORS can be found [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) and [here](https://www.w3.org/TR/cors/).
+    specifing the allowed origin (use `__ALL` for `*`). More information about CORS support in Orion can be found
+    in [the users manual](../user/cors.md).
 -   **-corsMaxAge <time>**. Specifies the maximum time (in seconds) preflight requests are allowed to be cached. Defaults
-    to 86400 if not set.
+    to 86400 if not set. More information about CORS support in Orion can be found in [the users manual](../user/cors.md).
 -   **-reqMutexPolicy <all|none|write|read>**. Specifies the internal
     mutex policy. See [performance tuning](perf_tuning.md#mutex-policy-impact-on-performance) documentation
     for details.

doc/manuals/contribution_guidelines.md

@@ -159,7 +159,7 @@ descriptive list of its parameters, and its return values.
 
 Example:
 
-```    
+```
 /* ****************************************************************************
 *
 * parseUrl - parse a URL and return its pieces
@@ -435,7 +435,7 @@ directly or indirectly are forced to have that construct as well.
 
 #### S2 (Object action naming convention):
 
-*Rule*: “objectAction” SHOULD be used, eg.:
+*Rule*: "objectAction" SHOULD be used, eg.:
 
 ```
 listInit()
@@ -450,6 +450,9 @@ resetList()
 findList()
 ```
 
+This rule is applied to variable names, function names and even file names (for files which
+contain only one external function so the name of the file is the name of the function).
+
 *Rationale*: a set of functions are ‘grouped’ thanks to their prefix (“object”, in the example: “list”).
 
 *How to check*: manually
@@ -677,7 +680,7 @@ X:X(int _i, float _f):  i(_i), f(_f)
 Y:Y(const std::string& _fooName, const std::string& _myLongFooName):
   fooName(_fooName),
   myLongFooName(_myLongFooName)
-{            
+{
 }
 ```
 
@@ -725,6 +728,28 @@ See [this question](https://stackoverflow.com/questions/44239212/how-do-c-compil
 
 *How to check*: manually
 
+#### S15 (Error output parameter at the end)
+
+*Rule*: in the case a function uses an output parameter to potencially provide error output to the caller, that
+parameter SHOULD be declared at the end of the parameters list, e.g.:
+
+```
++void mongoRegistrationGet
+(
+  ngsiv2::Registration*  regP,
+  const std::string&     regId,
+  const std::string&     tenant,
+  const std::string&     servicePath,
+  OrionError*            oeP
+);
+
+void myFunction(const std::string s, std::string* err);
+```
+
+*Rationale*: the code gets more ordered this way.
+
+*How to check*: manually
+
 ## Programming patterns
 
 Some patterns are not allowed in Orion Context Broker code, except if some strong reason justifies the use of it. 

doc/manuals/devel/README.md

@@ -1,6 +1,6 @@
 # <a name="top"></a>Development Manual
 
-*Note: This document describes Orion Context Broker as of release 1.7.x.*
+*Note: This document describes Orion Context Broker as of release 1.10.x.*
 
 ## Intended audience
 The intended audience of this manual is developers that need to understand the internals of the Orion Context Broker