Bug 1739702 - Rename IOUtils.touch to IOUtils.setModificationTime r=Gijs

Differential Revision: https://phabricator.services.mozilla.com/D131957

dom/chrome-webidl/IOUtils.webidl

@@ -161,7 +161,9 @@ namespace IOUtils {
   /**
    * Updates the |modification| time for the file at |path|.
    *
-   * @param path         An absolute file path identifying the file to touch.
+   * @param path         An absolute file path identifying the file whose
+   *                     modification time is to be set. This file must exist
+   *                     and will not be created.
    * @param modification An optional modification time for the file expressed in
    *                     milliseconds since the Unix epoch
    *                     (1970-01-01T00:00:00Z). The current system time is used
@@ -171,7 +173,7 @@ namespace IOUtils {
    *         milliseconds since the Unix epoch, otherwise rejects with a
    *         DOMException.
    */
-  Promise<long long> touch(DOMString path, optional long long modification);
+  Promise<long long> setModificationTime(DOMString path, optional long long modification);
   /**
    * Retrieves a (possibly empty) list of immediate children of the directory at
    * |path|. If the file at |path| is not a directory, this method resolves with

dom/docs/ioutils_migration.md

@@ -394,7 +394,7 @@ await IOUtils.makeDirectory(srcPath, destPath);
 `IOUtils` provides the following method to update a file's modification time.
 
 ```idl
-Promise<void> touch(DOMString path, optional long long modification);
+Promise<void> setModificationTime(DOMString path, optional long long modification);
 ```
 
 #### Example
@@ -406,7 +406,7 @@ await OS.File.setDates(path, new Date(), new Date());
 
 **`IOUtils`**
 ```js
-await IOUtils.touch(path, new Date().valueOf());
+await IOUtils.setModificationTime(path, new Date().valueOf());
 ```
 
 ### Get file metadata

dom/system/IOUtils.cpp

@@ -709,7 +709,7 @@ already_AddRefed<Promise> IOUtils::Copy(GlobalObject& aGlobal,
 }
 
 /* static */
-already_AddRefed<Promise> IOUtils::Touch(
+already_AddRefed<Promise> IOUtils::SetModificationTime(
     GlobalObject& aGlobal, const nsAString& aPath,
     const Optional<int64_t>& aModification) {
   MOZ_DIAGNOSTIC_ASSERT(XRE_IsParentProcess());
@@ -728,7 +728,7 @@ already_AddRefed<Promise> IOUtils::Touch(
     }
     DispatchAndResolve<int64_t>(state.ref()->mEventQueue, promise,
                                 [file = std::move(file), newTime]() {
-                                  return TouchSync(file, newTime);
+                                  return SetModificationTimeSync(file, newTime);
                                 });
   } else {
     RejectShuttingDown(promise);
@@ -1417,7 +1417,7 @@ Result<IOUtils::InternalFileInfo, IOUtils::IOError> IOUtils::StatSync(
 }
 
 /* static */
-Result<int64_t, IOUtils::IOError> IOUtils::TouchSync(
+Result<int64_t, IOUtils::IOError> IOUtils::SetModificationTimeSync(
     nsIFile* aFile, const Maybe<int64_t>& aNewModTime) {
   MOZ_ASSERT(!NS_IsMainThread());
 
@@ -1443,8 +1443,8 @@ Result<int64_t, IOUtils::IOError> IOUtils::TouchSync(
         IOError(NS_ERROR_ILLEGAL_VALUE)
             .WithMessage(
                 "Refusing to set the modification time of file(%s) to 0.\n"
-                "To use the current system time, call `touch` with no "
-                "arguments",
+                "To use the current system time, call `setModificationTime` "
+                "with no arguments",
                 aFile->HumanReadablePath().get()));
   }
 
@@ -1454,7 +1454,8 @@ Result<int64_t, IOUtils::IOError> IOUtils::TouchSync(
     IOError err(rv);
     if (IsFileNotFound(rv)) {
       return Err(
-          err.WithMessage("Could not touch file(%s) because it does not exist",
+          err.WithMessage("Could not set modification time of file(%s) "
+                          "because it does not exist",
                           aFile->HumanReadablePath().get()));
     }
     return Err(err);

dom/system/IOUtils.h

@@ -108,7 +108,7 @@ class IOUtils final {
                                         const nsAString& aDestPath,
                                         const CopyOptions& aOptions);
 
-  static already_AddRefed<Promise> Touch(
+  static already_AddRefed<Promise> SetModificationTime(
       GlobalObject& aGlobal, const nsAString& aPath,
       const Optional<int64_t>& aModification);
 
@@ -328,8 +328,8 @@ class IOUtils final {
    *
    * @return Timestamp of the file if the operation was successful, or an error.
    */
-  static Result<int64_t, IOError> TouchSync(nsIFile* aFile,
-                                            const Maybe<int64_t>& aNewModTime);
+  static Result<int64_t, IOError> SetModificationTimeSync(
+      nsIFile* aFile, const Maybe<int64_t>& aNewModTime);
 
   /**
    * Returns the immediate children of the directory at |aFile|, if any.

dom/system/tests/ioutils/chrome.ini

@@ -11,6 +11,6 @@ support-files =
 [test_ioutils_read_write_json.html]
 [test_ioutils_read_write_utf8.html]
 [test_ioutils_remove.html]
-[test_ioutils_stat_touch.html]
+[test_ioutils_stat_set_modification_time.html]
 [test_ioutils_worker.xhtml]
 [test_ioutils_set_permissions.html]

dom/system/tests/ioutils/test_ioutils_stat_touch.html → dom/system/tests/ioutils/test_ioutils_stat_set_modification_time.html

@@ -80,42 +80,42 @@
       );
     });
 
-    add_task(async function test_touch_and_stat() {
-      info("Test attempt to touch a file");
+    add_task(async function test_setModificationTime_and_stat() {
+      info("Test attempt to setModificationTime a file");
 
       const tmpDir = await PathUtils.getTempDir();
 
-      const tmpFileName = PathUtils.join(tmpDir, "test_touch_and_stat.tmp");
+      const tmpFileName = PathUtils.join(tmpDir, "test_setModificationTime_and_stat.tmp");
       await createFile(tmpFileName);
 
       const oldFileInfo = await IOUtils.stat(tmpFileName);
       await sleep(500);
 
       // Now update the time stamp.
-      const stamp = await IOUtils.touch(tmpFileName);
+      const stamp = await IOUtils.setModificationTime(tmpFileName);
       const newFileInfo = await IOUtils.stat(tmpFileName);
 
       ok(
         newFileInfo.lastModified > oldFileInfo.lastModified,
-        "IOUtils::touch can update the lastModified time stamp on the file system"
+        "IOUtils::setModificationTime can update the lastModified time stamp on the file system"
       );
       is(
         stamp,
         newFileInfo.lastModified,
-        "IOUtils::touch returns the updated time stamp."
+        "IOUtils::setModificationTime returns the updated time stamp."
       );
 
-      info("Test attempt to touch a directory");
-      const tmpDirName = PathUtils.join(tmpDir, "test_touch_and_stat.tmp.d");
+      info("Test attempt to setModificationTime a directory");
+      const tmpDirName = PathUtils.join(tmpDir, "test_setModificationTime_and_stat.tmp.d");
       await createDir(tmpDirName);
 
       await cleanup(tmpFileName, tmpDirName);
     });
 
-    add_task(async function test_touch_custom_mod_time() {
+    add_task(async function test_setModificationTime_custom_mod_time() {
       const tmpDir = await PathUtils.getTempDir();
 
-      const tempFileName = PathUtils.join(tmpDir, "test_touch_custom_mod_time.tmp");
+      const tempFileName = PathUtils.join(tmpDir, "test_setModificationTime_custom_mod_time.tmp");
       await createFile(tempFileName);
       const originalInfo = await IOUtils.stat(tempFileName);
       const now = originalInfo.lastModified;
@@ -124,21 +124,21 @@
 
       info("Test attempt to set modification time to the future");
       const future = now + oneMinute;
-      let newModTime = await IOUtils.touch(tempFileName, future);
+      let newModTime = await IOUtils.setModificationTime(tempFileName, future);
       const futureInfo = await IOUtils.stat(tempFileName);
-      Assert.less(originalInfo.lastModified, futureInfo.lastModified, "IOUtils::touch can set a future modification time for the file");
+      Assert.less(originalInfo.lastModified, futureInfo.lastModified, "IOUtils::setModificationTime can set a future modification time for the file");
 
-      is(newModTime, futureInfo.lastModified, "IOUtils::touch returns the updated time stamp");
-      is(newModTime, future, "IOUtils::touch return value matches the argument value exactly");
+      is(newModTime, futureInfo.lastModified, "IOUtils::setModificationTime returns the updated time stamp");
+      is(newModTime, future, "IOUtils::setModificationTime return value matches the argument value exactly");
 
       info("Test attempt to set modification time to the past");
       const past = now - 2 * oneMinute;
-      newModTime = await IOUtils.touch(tempFileName, past);
+      newModTime = await IOUtils.setModificationTime(tempFileName, past);
       const pastInfo = await IOUtils.stat(tempFileName);
-      Assert.greater(originalInfo.lastModified, pastInfo.lastModified, "IOUtils::touch can set a past modification time for the file");
+      Assert.greater(originalInfo.lastModified, pastInfo.lastModified, "IOUtils::setModificationTime can set a past modification time for the file");
 
-      is(newModTime, pastInfo.lastModified, "IOUtils::touch returns the updated time stamp");
-      is(newModTime, past, "IOUtils::touch return value matches the argument value exactly");
+      is(newModTime, pastInfo.lastModified, "IOUtils::setModificationTime returns the updated time stamp");
+      is(newModTime, past, "IOUtils::setModificationTime return value matches the argument value exactly");
 
       await cleanup(tempFileName);
     });
@@ -152,7 +152,7 @@
         const originalInfo = await IOUtils.stat(tempFileName);
 
         const future = originalInfo.lastModified + 6000;
-        await IOUtils.touch(tempFileName, future);
+        await IOUtils.setModificationTime(tempFileName, future);
         const futureInfo = await IOUtils.stat(tempFileName);
 
         ok(originalInfo.hasOwnProperty("creationTime"), "originalInfo has creationTime field");
@@ -169,25 +169,25 @@
       }
     });
 
-    add_task(async function test_touch_failures() {
-      info("Test attempt to touch a non-existing file");
+    add_task(async function test_setModificationTime_failures() {
+      info("Test attempt to setModificationTime a non-existing file");
       const tmpDir = await PathUtils.getTempDir();
-      const notExistsFile = PathUtils.join(tmpDir, "test_touch_not_exists.tmp");
+      const notExistsFile = PathUtils.join(tmpDir, "test_setModificationTime_not_exists.tmp");
 
       await Assert.rejects(
-        IOUtils.touch(notExistsFile),
-        /Could not touch file\(.*\) because it does not exist/,
-        "IOUtils::touch throws if the target file does not exist"
+        IOUtils.setModificationTime(notExistsFile),
+        /Could not set modification time of file\(.*\) because it does not exist/,
+        "IOUtils::setModificationTime throws if the target file does not exist"
       );
 
       info("Test attempt to set modification time to Epoch");
-      const tempFileName = PathUtils.join(tmpDir, "test_touch_epoch.tmp");
+      const tempFileName = PathUtils.join(tmpDir, "test_setModificationTime_epoch.tmp");
       await createFile(tempFileName);
 
       await Assert.rejects(
-        IOUtils.touch(tempFileName, 0),
+        IOUtils.setModificationTime(tempFileName, 0),
         /Refusing to set the modification time of file\(.*\) to 0/,
-        "IOUtils::touch cannot set the file modification time to Epoch"
+        "IOUtils::setModificationTime cannot set the file modification time to Epoch"
       );
 
       await cleanup(tempFileName);

toolkit/components/places/tests/unit/test_PlacesDBUtils_removeOldCorruptDBs.js

@@ -17,7 +17,7 @@ async function createfiles() {
       tmpPath: filePath + ".tmp",
     });
     Assert.ok(await IOUtils.exists(filePath), "file created: " + filePath);
-    await IOUtils.touch(filePath, setTime);
+    await IOUtils.setModificationTime(filePath, setTime);
   }
 }
 

toolkit/components/telemetry/tests/unit/test_TelemetrySend.js

@@ -41,7 +41,7 @@ function countPingTypes(pings) {
 
 function setPingLastModified(id, timestamp) {
   const path = OS.Path.join(TelemetryStorage.pingDirectoryPath, id);
-  return IOUtils.touch(path, timestamp);
+  return IOUtils.setModificationTime(path, timestamp);
 }
 
 // Mock out the send timer activity.

toolkit/mozapps/extensions/internal/AddonTestUtils.jsm

@@ -1354,7 +1354,7 @@ var AddonTestUtils = {
   },
 
   async promiseSetExtensionModifiedTime(path, time) {
-    await IOUtils.touch(path, time);
+    await IOUtils.setModificationTime(path, time);
 
     let iterator = new OS.File.DirectoryIterator(path);
     try {

toolkit/mozapps/extensions/test/xpcshell/test_schema_change.js

@@ -81,7 +81,7 @@ add_task(async function run_tests() {
       async action() {
         let stat = await IOUtils.stat(xpiPath);
         let newLastModTime = stat.lastModified + 60 * 1000;
-        await IOUtils.touch(xpiPath, newLastModTime);
+        await IOUtils.setModificationTime(xpiPath, newLastModTime);
       },
     },
   ];
@@ -107,7 +107,7 @@ add_task(async function run_tests() {
 
     // Make sure the timestamp of the extension is unchanged, so it is not
     // re-scanned for that reason.
-    await IOUtils.touch(xpiPath, fileInfo.lastModified);
+    await IOUtils.setModificationTime(xpiPath, fileInfo.lastModified);
 
     await test.action();