ADD upsert operation

CHANGES_NEXT_RELEASE

@@ -1,4 +1,5 @@
+- Add: upsert option for the POST /v2/entities operation (#3215)
 - Add: transient entities functionality (new reserved attribute: dateExpires) (#3000)
 - Add: "attrs" field in POST /v2/op/query (making "attributes" obsolete) (#2604)
 - Add: "expression" field in POST /v2/op/query (#2706)
-- Remove: "scopes" field in POST /v2/op/query (#2706)
+- Remove: "scopes" field in POST /v2/op/query (#2706)

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

@@ -1074,7 +1074,8 @@ the JSON entity representation format (described in a "JSON Entity Representatio
 
 Response:
 
-* Successful operation uses 201 Created. Reponse includes a `Location` header with the URL of the
+* Successful operation uses 201 Created (if upsert option is not used) or 204 No Content (if
+  upsert option is used). Response includes a `Location` header with the URL of the
   created entity.
 * Errors use a non-2xx and (optionally) an error payload. See subsection on "Error Responses" for
   more details.
@@ -1106,13 +1107,21 @@ Response:
       + Members
           + keyValues - when used, the request payload uses the `keyValues` simplified entity
             representation. See "Simplified Entity Representation" section for details.
+          + upsert - when used, entity is updated if already exits. If upsert is not used and
+            the entity already exist a `422 Unprocessable Entity` error is returned.
 
 + Response 201
 
     + Headers
 
             Location: /v2/entities/Bcn-Welt?type=Room
 
++ Response 204
+
+    + Headers
+
+            Location: /v2/entities/Bcn-Welt?type=Room
+
 
 ## Entity by ID [/v2/entities/{entityId}{?type,attrs,options}]
 

src/lib/common/globals.h

@@ -136,6 +136,7 @@
 #define OPT_DATE_CREATED    DATE_CREATED
 #define OPT_DATE_MODIFIED   DATE_MODIFIED
 #define OPT_NO_ATTR_DETAIL  "noAttrDetail"
+#define OPT_UPSERT          "upsert"
 
 
 

src/lib/rest/ConnectionInfo.cpp

@@ -47,7 +47,8 @@ static const char* validOptions[] =
   OPT_UNIQUE_VALUES,
   OPT_DATE_CREATED,
   OPT_DATE_MODIFIED,
-  OPT_NO_ATTR_DETAIL
+  OPT_NO_ATTR_DETAIL,
+  OPT_UPSERT
 };
 
 

src/lib/serviceRoutinesV2/postEntities.cpp

@@ -66,6 +66,7 @@ static bool legalEntityLength(Entity* eP, const std::string& servicePath)
 *
 * URI parameters:
 *   options=keyValues
+*   options=upsert
 *
 * 01. Fill in UpdateContextRequest
 * 02. Call standard op postUpdateContext
@@ -80,7 +81,8 @@ std::string postEntities
   ParseData*                 parseDataP
 )
 {
-  Entity*  eP = &parseDataP->ent.res;
+  Entity*   eP = &parseDataP->ent.res;
+  bool  upsert = ciP->uriParamOptions[OPT_UPSERT];
 
   if (!legalEntityLength(eP, ciP->httpHeaders.servicePath))
   {
@@ -94,12 +96,28 @@ std::string postEntities
     return out;
   }
 
-  // 01. Fill in UpdateContextRequest
-  parseDataP->upcr.res.fill(eP, ActionTypeAppendStrict);
+  // Set some aspects depending on upsert or not upsert
+  ActionType      actionType;
+  Ngsiv2Flavour   ngsiv2flavour;
+  HttpStatusCode  sccCodeOnSuccess;
+  if (upsert)
+  {
+    actionType       = ActionTypeAppend;
+    ngsiv2flavour    = NGSIV2_NO_FLAVOUR;
+    sccCodeOnSuccess = SccNoContent;
+  }
+  else
+  {
+    actionType       = ActionTypeAppendStrict;
+    ngsiv2flavour    = NGSIV2_FLAVOUR_ONCREATE;
+    sccCodeOnSuccess = SccCreated;
+  }
 
+  // 01. Fill in UpdateContextRequest
+  parseDataP->upcr.res.fill(eP, actionType);
 
   // 02. Call standard op postUpdateContext
-  postUpdateContext(ciP, components, compV, parseDataP, NGSIV2_FLAVOUR_ONCREATE);
+  postUpdateContext(ciP, components, compV, parseDataP, ngsiv2flavour);
 
   //
   // 03. Check error - 3 different ways to get an error from postUpdateContext ... :-(
@@ -132,7 +150,7 @@ std::string postEntities
 
     ciP->httpHeader.push_back(HTTP_RESOURCE_LOCATION);
     ciP->httpHeaderValue.push_back(location);
-    ciP->httpStatusCode = SccCreated;
+    ciP->httpStatusCode = sccCodeOnSuccess;
   }
 
   // 04. Cleanup and return result

test/functionalTest/cases/3215_upsert_op/upsert_op_as_create.test

@@ -0,0 +1,92 @@
+# Copyright 2018 Telefonica Investigacion y Desarrollo, S.A.U
+#
+# This file is part of Orion Context Broker.
+#
+# Orion Context Broker is free software: you can redistribute it and/or
+# modify it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# Orion Context Broker is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
+# General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with Orion Context Broker. If not, see http://www.gnu.org/licenses/.
+#
+# For those usages not covered by this license please contact with
+# iot_support at tid dot es
+
+# VALGRIND_READY - to mark the test ready for valgrindTestSuite.sh
+
+--NAME--
+Upsert operation as create
+
+--SHELL-INIT--
+dbInit CB
+brokerStart CB 0
+
+--SHELL--
+
+#
+# 01. Creating entity POST /v2/entities?options=upsert E with attribute A=1, see error
+# 02. Get entity, see A=1
+#
+
+
+echo "01. Creating entity POST /v2/entities?options=upsert E with attribute A=1"
+echo "========================================================================="
+payload='{
+  "id": "E",
+  "type": "T",
+  "A": {
+    "value": 1,
+    "type": "Number"
+  }
+}'
+orionCurl --url '/v2/entities?options=upsert' --payload "$payload"
+echo
+echo
+
+
+echo "02. Get entity, see A=1"
+echo "======================="
+orionCurl --url /v2/entities/E
+echo
+echo
+
+
+--REGEXPECT--
+01. Creating entity POST /v2/entities?options=upsert E with attribute A=1
+=========================================================================
+HTTP/1.1 204 No Content
+Content-Length: 0
+Location: /v2/entities/E?type=T
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+
+
+02. Get entity, see A=1
+=======================
+HTTP/1.1 200 OK
+Content-Length: 67
+Content-Type: application/json
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+{
+    "A": {
+        "metadata": {},
+        "type": "Number",
+        "value": 1
+    },
+    "id": "E",
+    "type": "T"
+}
+
+
+--TEARDOWN--
+brokerStop CB
+dbDrop CB

test/functionalTest/cases/3215_upsert_op/upsert_op_as_update.test

@@ -0,0 +1,153 @@
+# Copyright 2018 Telefonica Investigacion y Desarrollo, S.A.U
+#
+# This file is part of Orion Context Broker.
+#
+# Orion Context Broker is free software: you can redistribute it and/or
+# modify it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# Orion Context Broker is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero
+# General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with Orion Context Broker. If not, see http://www.gnu.org/licenses/.
+#
+# For those usages not covered by this license please contact with
+# iot_support at tid dot es
+
+# VALGRIND_READY - to mark the test ready for valgrindTestSuite.sh
+
+--NAME--
+Upsert operation as update
+
+--SHELL-INIT--
+dbInit CB
+brokerStart CB 0
+
+--SHELL--
+
+#
+# 01. Creating entity POST /v2/entities E with attribute A=1
+# 02. Get entity, see A=1
+# 03. Update entity using POST /v2/entity?options=upsert attributes A=2 B=3
+# 04. Get entity, see A=2 B=3
+#
+
+echo "01. Creating entity POST /v2/entities E with attribute A=1"
+echo "=========================================================="
+payload='{
+  "id": "E",
+  "type": "T",
+  "A": {
+    "value": 1,
+    "type": "Number"
+  }
+}'
+orionCurl --url '/v2/entities' --payload "$payload"
+echo
+echo
+
+
+echo "02. Get entity, see A=1"
+echo "======================="
+orionCurl --url /v2/entities/E
+echo
+echo
+
+
+echo "03. Update entity using POST /v2/entity?options=upsert attributes A=2 B=3"
+echo "========================================================================="
+payload='{
+  "id": "E",
+  "type": "T",
+  "A": {
+    "value": 2,
+    "type": "Number"
+  },
+  "B": {
+    "value": 3,
+    "type": "Number"
+  }
+}'
+orionCurl --url '/v2/entities?options=upsert' --payload "$payload"
+echo
+echo
+
+
+echo "04. Get entity, see A=2 B=3"
+echo "==========================="
+orionCurl --url /v2/entities/E
+echo
+echo
+
+
+--REGEXPECT--
+01. Creating entity POST /v2/entities E with attribute A=1
+==========================================================
+HTTP/1.1 201 Created
+Content-Length: 0
+Location: /v2/entities/E?type=T
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+
+
+02. Get entity, see A=1
+=======================
+HTTP/1.1 200 OK
+Content-Length: 67
+Content-Type: application/json
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+{
+    "A": {
+        "metadata": {},
+        "type": "Number",
+        "value": 1
+    },
+    "id": "E",
+    "type": "T"
+}
+
+
+03. Update entity using POST /v2/entity?options=upsert attributes A=2 B=3
+=========================================================================
+HTTP/1.1 204 No Content
+Content-Length: 0
+Location: /v2/entities/E?type=T
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+
+
+04. Get entity, see A=2 B=3
+===========================
+HTTP/1.1 200 OK
+Content-Length: 113
+Content-Type: application/json
+Fiware-Correlator: REGEX([0-9a-f\-]{36})
+Date: REGEX(.*)
+
+{
+    "A": {
+        "metadata": {},
+        "type": "Number",
+        "value": 2
+    },
+    "B": {
+        "metadata": {},
+        "type": "Number",
+        "value": 3
+    },
+    "id": "E",
+    "type": "T"
+}
+
+
+--TEARDOWN--
+brokerStop CB
+dbDrop CB