[pull] develop from IQSS:develop

doc/release-notes/12008-dataset-api-locks.md

@@ -0,0 +1 @@
+The API returning information about datasets (`/api/datasets/{id}`) now includes a `locks` field containing a list of the types of all existing locks, e.g. `"locks": ["InReview"]`.

doc/sphinx-guides/source/api/search.rst

@@ -17,7 +17,6 @@ The parameters and JSON response are partly inspired by the `GitHub Search API <
 
 Please note that in Dataverse Software 4.3 and older the "citation" field wrapped the persistent ID URL in an ``<a>`` tag but this has been changed to plaintext. If you want the old value with HTML in it, a new field called "citationHtml" can be used.
 
-
 Parameters
 ----------
 
@@ -27,7 +26,7 @@ Name             Type     Description
 q                string   The search term or terms. Using "title:data" will search only the "title" field. "*" can be used as a wildcard either alone or adjacent to a term (i.e. "bird*"). For example, https://demo.dataverse.org/api/search?q=title:data . For a list of fields to search, please see https://github.com/IQSS/dataverse/issues/2558 (for now).
 type             string   Can be either "dataverse", "dataset", or "file". Multiple "type" parameters can be used to include multiple types (i.e. ``type=dataset&type=file``). If omitted, all types will be returned.  For example, https://demo.dataverse.org/api/search?q=*&type=dataset
 subtree          string   The identifier of the Dataverse collection to which the search should be narrowed. The subtree of this Dataverse collection and all its children will be searched.  Multiple "subtree" parameters can be used to include multiple Dataverse collections. For example, https://demo.dataverse.org/api/search?q=data&subtree=birds&subtree=cats .
-sort             string   The sort field. Supported values include "name", "date" and "relevance". See example under "order".
+sort             string   The sort field. Supported values include "name", "date", and "score". Sorting by "score" orders by **relevance** and is the default if this parameter is omitted.
 order            string   The order in which to sort. Can either be "asc" or "desc".  For example, https://demo.dataverse.org/api/search?q=data&sort=name&order=asc
 per_page         int      The number of results to return per request. The default is 10. The max is 1000. See :ref:`iteration example <iteration-example>`.
 start            int      A cursor for paging through search results. See :ref:`iteration example <iteration-example>`.

src/main/java/edu/harvard/iq/dataverse/util/json/JsonPrinter.java

@@ -486,6 +486,13 @@ public static JsonObjectBuilder json(Dataset ds, Boolean returnOwners) {
             bld.add("isPartOf", getOwnersFromDvObject(ds));
         }
         bld.add("datasetType", ds.getDatasetType().getName());
+
+        JsonArrayBuilder locksArrayBuilder = Json.createArrayBuilder();
+        for (DatasetLock lock : ds.getLocks()) {
+            locksArrayBuilder.add(lock.getReason().toString());
+        }
+        bld.add("locks", locksArrayBuilder);
+
         return bld;
     }
 

src/test/java/edu/harvard/iq/dataverse/api/DatasetsIT.java

@@ -3077,12 +3077,19 @@ public void testDatasetLocksApi() {
                 .statusCode(200);
 
         // Check again: 
-        // This should return an empty list, as the dataset should have no locks just yet:
+        // This should no longer return an empty list, as the dataset now has a lock:
         checkDatasetLocks = UtilIT.checkDatasetLocks(datasetId.longValue(), "Ingest", apiToken);
         checkDatasetLocks.prettyPrint();
         checkDatasetLocks.then().assertThat()
                 .body("data[0].lockType", equalTo("Ingest"))
                 .statusCode(200);
+
+        // Confirm that when getting the dataset, the lock is also listed
+        Response getDatasetJson = UtilIT.nativeGet(datasetId, apiToken);
+        getDatasetJson.prettyPrint();
+        getDatasetJson.then().assertThat()
+                .body("data.locks[0]", equalTo("Ingest"))
+                .statusCode(200);
 
         // Try to lock the dataset with the same type lock, AGAIN 
         // (this should fail, of course!)
@@ -3197,6 +3204,13 @@ public void testDatasetLocksApi() {
         checkDatasetLocks.then().assertThat()
                 .body("data", equalTo(emptyArray))
                 .statusCode(200);
+
+        // Confirm that when getting the dataset, the lock is also no longer listed
+        getDatasetJson = UtilIT.nativeGet(datasetId, apiToken);
+        getDatasetJson.prettyPrint();
+        getDatasetJson.then().assertThat()
+                .body("data.locks", equalTo(emptyArray))
+                .statusCode(200);
     }
 
     /**

src/test/java/edu/harvard/iq/dataverse/api/InReviewWorkflowIT.java

@@ -6,6 +6,7 @@
 import io.restassured.response.Response;
 import edu.harvard.iq.dataverse.authorization.DataverseRole;
 import jakarta.json.Json;
+import jakarta.json.JsonArray;
 import jakarta.json.JsonObjectBuilder;
 
 import static edu.harvard.iq.dataverse.UserNotification.Type.*;
@@ -120,6 +121,13 @@ public void testCuratorSendsCommentsToAuthor() {
                 .body("message", equalTo("You cannot submit this dataset for review because it is already in review."))
                 .statusCode(FORBIDDEN.getStatusCode());
 
+        // Confirm that when getting the dataset, the "InReview" lock is listed
+        Response getDatasetJson = UtilIT.nativeGet(datasetId, authorApiToken);
+        getDatasetJson.prettyPrint();
+        getDatasetJson.then().assertThat()
+                .body("data.locks[0]", equalTo("InReview"))
+                .statusCode(200);
+
         Response authorsChecksForCommentsPrematurely = UtilIT.getNotifications(authorApiToken);
         authorsChecksForCommentsPrematurely.prettyPrint();
         authorsChecksForCommentsPrematurely.then().assertThat()
@@ -429,6 +437,14 @@ public void testCuratorSendsCommentsToAuthor() {
                 //   .body("data[3].reasonsForReturn", equalTo(null))
                 .statusCode(OK.getStatusCode());
 
+        // Confirm that when getting the dataset, the "InReview" lock is no longer listed
+        JsonArray emptyArray = Json.createArrayBuilder().build();
+        getDatasetJson = UtilIT.nativeGet(datasetId, authorApiToken);
+        getDatasetJson.prettyPrint();
+        getDatasetJson.then().assertThat()
+                .body("data.locks", equalTo(emptyArray))
+                .statusCode(200);
+
         // These println's are here in case you want to log into the GUI to see what notifications look like.
         System.out.println("Curator username/password: " + curatorUsername);
         System.out.println("Author username/password: " + authorUsername);