per review comments

Author: stevenwinship

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

@@ -4612,7 +4612,7 @@ Updating File Metadata
 
 Updates the file metadata for an existing file where ``ID`` is the database id of the file to update or ``PERSISTENT_ID`` is the persistent id (DOI or Handle) of the file. Requires a ``jsonString`` expressing the new metadata. No metadata from the previous version of this file will be persisted, so if you want to update a specific field first get the json with the above command and alter the fields you want.
 
-Optional Parameter for verifying that the Dataset Version being edited is the latest version can be added &datasetVersionId=12345. This is to prevent stale data from being edited.
+Optional Parameter for verifying that the Dataset Version being edited is the latest version can be added &sourceInternalVersionNumber=12345. This is to prevent stale data from being edited. The value for sourceInternalVersionNumber comes from ``datasetVersionId`` in the response to get $SERVER_URL/api/files/$ID API call
 
 A curl example using an ``ID``
 
@@ -4645,15 +4645,15 @@ A curl example using a ``PERSISTENT_ID``
 
   curl -H "X-Dataverse-key:$API_TOKEN" -X POST \
     -F 'jsonData={"description":"My description bbb.","provFreeform":"Test prov freeform","categories":["Data"],"dataFileTags":["Survey"],"restrict":false}' \
-    "$SERVER_URL/api/files/:persistentId/metadata?persistentId=$PERSISTENT_ID&datasetVersionId=$VERSION_ID"
+    "$SERVER_URL/api/files/:persistentId/metadata?persistentId=$PERSISTENT_ID&sourceInternalVersionNumber=$VERSION_ID"
 
 The fully expanded example above (without environment variables) looks like this:
 
 .. code-block:: bash
 
   curl -H "X-Dataverse-key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -X POST \
     -F 'jsonData={"description":"My description bbb.","provFreeform":"Test prov freeform","categories":["Data"],"dataFileTags":["Survey"],"restrict":false}' \
-    "https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.5072/FK2/AAA000&datasetVersionId=12345"
+    "https://demo.dataverse.org/api/files/:persistentId/metadata?persistentId=doi:10.5072/FK2/AAA000&sourceInternalVersionNumber=12345"
 
 Note: To update the 'tabularTags' property of file metadata, use the 'dataFileTags' key when making API requests. This property is used to update the 'tabularTags' of the file metadata.
 

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

@@ -451,6 +451,15 @@ protected void validateInternalVersionNumberIsNotOutdated(Dataset dataset, int i
         }
     }
 
+    protected void validateInternalVersionNumberIsNotOutdated(DataFile dataFile, int internalVersion) throws WrappedResponse {
+        logger.severe(">>>> internalVersion:"+internalVersion+"  dataFile.getFileMetadata().getDatasetVersion().getId():"+dataFile.getFileMetadata().getDatasetVersion().getId());
+        if (dataFile.getFileMetadata().getDatasetVersion().getId() > internalVersion) {
+            throw new WrappedResponse(
+                    badRequest(BundleUtil.getStringFromBundle("abstractApiBean.error.datafileInternalVersionNumberIsOutdated", Collections.singletonList(Integer.toString(internalVersion))))
+            );
+        }
+    }
+
     protected DataFile findDataFileOrDie(String id) throws WrappedResponse {
         DataFile datafile;
         if (id.equals(PERSISTENT_ID_KEY)) {

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

@@ -410,7 +410,7 @@ public Response deleteFileInDataset(@Context ContainerRequestContext crc, @PathP
     @AuthRequired
     @Path("{id}/metadata")
     public Response updateFileMetadata(@Context ContainerRequestContext crc, @FormDataParam("jsonData") String jsonData,
-                    @PathParam("id") String fileIdOrPersistentId, @QueryParam("datasetVersionId") String datasetVersionId
+                    @PathParam("id") String fileIdOrPersistentId, @QueryParam("sourceInternalVersionNumber") Integer sourceInternalVersionNumber
         ) throws CommandException {
 
         FileMetadata upFmd = null;
@@ -429,10 +429,12 @@ public Response updateFileMetadata(@Context ContainerRequestContext crc, @FormDa
                 return error(BAD_REQUEST, "Error attempting get the requested data file.");
             }
 
-            String latestDatasetVersion = String.valueOf(df.getFileMetadata().getDatasetVersion().getId());
-            if (datasetVersionId != null && latestDatasetVersion != null &&
-                    !latestDatasetVersion.equals(datasetVersionId)) {
-                return error(Response.Status.BAD_REQUEST, BundleUtil.getStringFromBundle("file.metadata.message.parallelUpdateError"));
+            if (sourceInternalVersionNumber != null) {
+                try {
+                    validateInternalVersionNumberIsNotOutdated(df, sourceInternalVersionNumber);
+                } catch (WrappedResponse wr) {
+                    return wr.getResponse();
+                }
             }
 
             //You shouldn't be trying to edit a datafile that has been replaced

src/main/java/propertyFiles/Bundle.properties

@@ -1945,7 +1945,6 @@ file.metaData.dataFile.dataTab.unf=UNF
 file.metaData.dataFile.dataTab.variables=Variables
 file.metaData.dataFile.dataTab.observations=Observations
 file.metaData.fileAccess=File Access: 
-file.metadata.message.parallelUpdateError=Changes cannot be saved. This metadata has been edited since this page was opened. To continue, copy your changes, refresh the page to see the recent updates, and re-enter any changes you want to save.
 file.addDescription=Add file description...
 file.tags=Tags
 file.editTags=Edit Tags
@@ -3206,3 +3205,4 @@ updateDatasetFieldsCommand.api.processDatasetUpdate.parseError=Error parsing dat
 
 #AbstractApiBean.java
 abstractApiBean.error.datasetInternalVersionNumberIsOutdated=Dataset internal version number {0} is outdated
+abstractApiBean.error.datafileInternalVersionNumberIsOutdated=File Metadata internal version number {0} is outdated

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

@@ -3278,7 +3278,7 @@ public void testUpdateWithEmptyFieldsAndVersionCheck() {
         updateResponse.prettyPrint();
         updateResponse.then().assertThat()
                 .body("status", equalTo(ApiConstants.STATUS_ERROR))
-                .body("message", startsWith(BundleUtil.getStringFromBundle("file.metadata.message.parallelUpdateError")))
+                .body("message", equalTo(BundleUtil.getStringFromBundle("abstractApiBean.error.datafileInternalVersionNumberIsOutdated",Collections.singletonList(datasetVersionId))))
                 .statusCode(BAD_REQUEST.getStatusCode());
 
         // Second user refreshes and updates. Should pass now

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

@@ -1100,7 +1100,7 @@ static Response updateFileMetadata(String fileIdOrPersistentId, String jsonAsStr
             optionalQueryParam = "?persistentId=" + fileIdOrPersistentId;
         }
         if (datasetVersionId != null) {
-            optionalQueryParam = optionalQueryParam + (optionalQueryParam.isEmpty() ? "?" : "&") + "datasetVersionId=" + datasetVersionId;
+            optionalQueryParam = optionalQueryParam + (optionalQueryParam.isEmpty() ? "?" : "&") + "sourceInternalVersionNumber=" + datasetVersionId;
         }
         RequestSpecification requestSpecification = given()
                 .header(API_TOKEN_HTTP_HEADER, apiToken);