10286 add owner info

doc/release-notes/10286-return-owner-added-to-get-apis.md

@@ -0,0 +1,5 @@
+The API endpoints for getting datasets, Dataverse collections, and datafiles have been extended to support the following optional 'returnOwners' query parameter.
+
+Including the parameter and setting it to true will add a hierarchy showing which dataset and dataverse collection(s) the object is part of to the json object returned. 
+
+

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

@@ -88,6 +88,14 @@ The fully expanded example above (without environment variables) looks like this
 
   curl "https://demo.dataverse.org/api/dataverses/root"
 
+If you want to include the Dataverse collections that this collection is part of, you must set ``returnOwners`` query parameter to ``true``.
+
+Usage example:
+
+.. code-block:: bash
+
+  curl "https://demo.dataverse.org/api/dataverses/root?returnOwners=true"
+
 To view an unpublished Dataverse collection:
 
 .. code-block:: bash
@@ -910,6 +918,14 @@ The fully expanded example above (without environment variables) looks like this
 
 The dataset id can be extracted from the response retrieved from the API which uses the persistent identifier (``/api/datasets/:persistentId/?persistentId=$PERSISTENT_IDENTIFIER``).
 
+If you want to include the Dataverse collections that this dataset is part of, you must set ``returnOwners`` query parameter to ``true``.
+
+Usage example:
+
+.. code-block:: bash
+
+  curl "https://demo.dataverse.org/api/datasets/24?returnOwners=true"
+
 List Versions of a Dataset
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1016,6 +1032,14 @@ Usage example:
 
   curl "https://demo.dataverse.org/api/datasets/24/versions/1.0?includeDeaccessioned=true"
 
+If you want to include the Dataverse collections that this dataset version is part of, you must set ``returnOwners`` query parameter to ``true``.
+
+Usage example:
+
+.. code-block:: bash
+
+  curl "https://demo.dataverse.org/api/datasets/24/versions/1.0?returnOwners=true"
+
 .. _export-dataset-metadata-api:
 
 Export Metadata of a Dataset in Various Formats
@@ -2585,6 +2609,15 @@ Get Dataset By Private URL Token
 
   curl "$SERVER_URL/api/datasets/privateUrlDatasetVersion/$PRIVATE_URL_TOKEN"
 
+If you want to include the Dataverse collections that this dataset is part of, you must set ``returnOwners`` query parameter to ``true``.
+
+Usage example:
+
+.. code-block:: bash
+
+  curl "https://demo.dataverse.org/api/datasets/privateUrlDatasetVersion/a56444bc-7697-4711-8964-e0577f055fd2?returnOwners=true"
+
+
 .. _get-citation:
 
 Get Citation
@@ -2892,6 +2925,27 @@ The fully expanded example above (without environment variables) looks like this
 
   curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/J8SJZB&returnDatasetVersion=true"
 
+If you want to include the dataset and collections that the file is part of in the response, there is an optional parameter for this called ``returnOwners`` whose default value is ``false``.
+
+Usage example:
+
+.. code-block:: bash
+
+  export SERVER_URL=https://demo.dataverse.org
+  export PERSISTENT_IDENTIFIER=doi:10.5072/FK2/J8SJZB
+  export DATASET_VERSION=:draft
+  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+  curl -H "X-Dataverse-key:$API_TOKEN" "$SERVER_URL/api/files/:persistentId/versions/$DATASET_VERSION?persistentId=$PERSISTENT_IDENTIFIER&returnOwners=true"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" "https://demo.dataverse.org/api/files/:persistentId/versions/:draft?persistentId=doi:10.5072/FK2/J8SJZB&returnOwners=true"
+
+
+
 Adding Files
 ~~~~~~~~~~~~
 

src/main/java/edu/harvard/iq/dataverse/api/Datasets.java

@@ -186,11 +186,11 @@ public interface DsVersionHandler<T> {
     @GET
     @AuthRequired
     @Path("{id}")
-    public Response getDataset(@Context ContainerRequestContext crc, @PathParam("id") String id, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response) {
+    public Response getDataset(@Context ContainerRequestContext crc, @PathParam("id") String id, @Context UriInfo uriInfo, @Context HttpHeaders headers, @Context HttpServletResponse response,  @QueryParam("returnOwners") boolean returnOwners) {
         return response( req -> {
             final Dataset retrieved = execCommand(new GetDatasetCommand(req, findDatasetOrDie(id)));
             final DatasetVersion latest = execCommand(new GetLatestAccessibleDatasetVersionCommand(req, retrieved));
-            final JsonObjectBuilder jsonbuilder = json(retrieved);
+            final JsonObjectBuilder jsonbuilder = json(retrieved, returnOwners);
             //Report MDC if this is a released version (could be draft if user has access, or user may not have access at all and is not getting metadata beyond the minimum)
             if((latest != null) && latest.isReleased()) {
                 MakeDataCountLoggingServiceBean.MakeDataCountEntry entry = new MakeDataCountEntry(uriInfo, headers, dvRequestService, retrieved);
@@ -421,6 +421,7 @@ public Response getVersion(@Context ContainerRequestContext crc,
                                @PathParam("versionId") String versionId,
                                @QueryParam("excludeFiles") Boolean excludeFiles,
                                @QueryParam("includeDeaccessioned") boolean includeDeaccessioned,
+                               @QueryParam("returnOwners") boolean returnOwners,
                                @Context UriInfo uriInfo,
                                @Context HttpHeaders headers) {
         return response( req -> {
@@ -439,7 +440,7 @@ public Response getVersion(@Context ContainerRequestContext crc,
             if (excludeFiles == null ? true : !excludeFiles) {
                 dsv = datasetversionService.findDeep(dsv.getId());
             }
-            return ok(json(dsv, excludeFiles == null ? true : !excludeFiles));
+            return ok(json(dsv, null, excludeFiles == null ? true : !excludeFiles, returnOwners));
         }, getRequestUser(crc));
     }
 
@@ -4386,7 +4387,7 @@ public Response getDatasetSummaryFieldNames() {
 
     @GET
     @Path("privateUrlDatasetVersion/{privateUrlToken}")
-    public Response getPrivateUrlDatasetVersion(@PathParam("privateUrlToken") String privateUrlToken) {
+    public Response getPrivateUrlDatasetVersion(@PathParam("privateUrlToken") String privateUrlToken, @QueryParam("returnOwners") boolean returnOwners) {
         PrivateUrlUser privateUrlUser = privateUrlService.getPrivateUrlUserFromToken(privateUrlToken);
         if (privateUrlUser == null) {
             return notFound("Private URL user not found");
@@ -4403,9 +4404,9 @@ public Response getPrivateUrlDatasetVersion(@PathParam("privateUrlToken") String
         JsonObjectBuilder responseJson;
         if (isAnonymizedAccess) {
             List<String> anonymizedFieldTypeNamesList = new ArrayList<>(Arrays.asList(anonymizedFieldTypeNames.split(",\\s")));
-            responseJson = json(dsv, anonymizedFieldTypeNamesList, true);
+            responseJson = json(dsv, anonymizedFieldTypeNamesList, true, returnOwners);
         } else {
-            responseJson = json(dsv, true);
+            responseJson = json(dsv, null, true, returnOwners);
         }
         return ok(responseJson);
     }

src/main/java/edu/harvard/iq/dataverse/api/Dataverses.java

@@ -610,10 +610,11 @@ private Dataset parseDataset(String datasetJson) throws WrappedResponse {
     @GET
     @AuthRequired
     @Path("{identifier}")
-    public Response viewDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String idtf) {
+    public Response getDataverse(@Context ContainerRequestContext crc, @PathParam("identifier") String idtf, @QueryParam("returnOwners") boolean returnOwners) {
         return response(req -> ok(
             json(execCommand(new GetDataverseCommand(req, findDataverseOrDie(idtf))),
-                settingsService.isTrueForKey(SettingsServiceBean.Key.ExcludeEmailFromExport, false)
+                settingsService.isTrueForKey(SettingsServiceBean.Key.ExcludeEmailFromExport, false),
+                returnOwners
             )), getRequestUser(crc));
     }
 

src/main/java/edu/harvard/iq/dataverse/api/Files.java

@@ -487,9 +487,10 @@ public Response getFileData(@Context ContainerRequestContext crc,
                                 @PathParam("id") String fileIdOrPersistentId,
                                 @QueryParam("includeDeaccessioned") boolean includeDeaccessioned,
                                 @QueryParam("returnDatasetVersion") boolean returnDatasetVersion,
+                                @QueryParam("returnOwners") boolean returnOwners,
                                 @Context UriInfo uriInfo,
                                 @Context HttpHeaders headers) {
-        return response( req -> getFileDataResponse(req, fileIdOrPersistentId, DS_VERSION_LATEST, includeDeaccessioned, returnDatasetVersion, uriInfo, headers), getRequestUser(crc));
+        return response( req -> getFileDataResponse(req, fileIdOrPersistentId, DS_VERSION_LATEST, includeDeaccessioned, returnDatasetVersion, returnOwners, uriInfo, headers), getRequestUser(crc));
     }
 
     @GET
@@ -500,16 +501,18 @@ public Response getFileData(@Context ContainerRequestContext crc,
                                 @PathParam("datasetVersionId") String datasetVersionId,
                                 @QueryParam("includeDeaccessioned") boolean includeDeaccessioned,
                                 @QueryParam("returnDatasetVersion") boolean returnDatasetVersion,
+                                @QueryParam("returnOwners") boolean returnOwners,
                                 @Context UriInfo uriInfo,
                                 @Context HttpHeaders headers) {
-        return response( req -> getFileDataResponse(req, fileIdOrPersistentId, datasetVersionId, includeDeaccessioned, returnDatasetVersion, uriInfo, headers), getRequestUser(crc));
+        return response( req -> getFileDataResponse(req, fileIdOrPersistentId, datasetVersionId, includeDeaccessioned, returnDatasetVersion, returnOwners, uriInfo, headers), getRequestUser(crc));
     }
 
     private Response getFileDataResponse(final DataverseRequest req,
                                          String fileIdOrPersistentId,
                                          String datasetVersionId,
                                          boolean includeDeaccessioned,
                                          boolean returnDatasetVersion,
+                                         boolean returnOwners,
                                          UriInfo uriInfo,
                                          HttpHeaders headers) throws WrappedResponse {
         final DataFile dataFile = execCommand(new GetDataFileCommand(req, findDataFileOrDie(fileIdOrPersistentId)));
@@ -542,14 +545,15 @@ public Command<FileMetadata> handleLatestPublished() {
         if (fileMetadata.getDatasetVersion().isReleased()) {
             MakeDataCountLoggingServiceBean.MakeDataCountEntry entry = new MakeDataCountLoggingServiceBean.MakeDataCountEntry(uriInfo, headers, dvRequestService, dataFile);
             mdcLogService.logEntry(entry);
-        }
-
+        } 
+                    
         return Response.ok(Json.createObjectBuilder()
-                        .add("status", ApiConstants.STATUS_OK)
-                        .add("data", json(fileMetadata, returnDatasetVersion)).build())
+                .add("status", ApiConstants.STATUS_OK)
+                .add("data", json(fileMetadata, returnOwners, returnDatasetVersion)).build())
                 .type(MediaType.APPLICATION_JSON)
                 .build();
     }
+
 
     @GET
     @AuthRequired