Warn that Files.createTempDir and FileBackedOutputStream don't wo…

…rk under Windows anymore (if ever they did). Relates to: - #4011 - #2575 - #2686 Also, fix some Javadoc. RELNOTES=n/a PiperOrigin-RevId: 536752422
google · May 31, 2023 · 3dfe363 · 3dfe363
1 parent b047302
commit 3dfe363
Show file tree

Hide file tree

Showing 6 changed files with 36 additions and 10 deletions.
diff --git a/android/guava/src/com/google/common/io/FileBackedOutputStream.java b/android/guava/src/com/google/common/io/FileBackedOutputStream.java
@@ -58,6 +58,13 @@
  *
  * <p>This class is thread-safe.
  *
+ * <p><b>Warning for Windows users:</b> This class is one of the Guava APIs known to <i>not</i> work
+ * under Windows. Note that <a href="https://github.com/google/guava/issues/2686">we do not run our
+ * CI under Windows</a>, <a href="https://github.com/google/guava/issues/2130">we know that some of
+ * our tests fail under Windows</a>, and <a href="https://guava.dev/#important-warnings">we warn
+ * about using some features of Guava under Windows</a>, especially I/O features, and that warning
+ * applies even to APIs whose documentation doesn't include individual warnings like this one.
+ *
  * @author Chris Nokleberg
  * @since 1.0
  */

diff --git a/android/guava/src/com/google/common/io/Files.java b/android/guava/src/com/google/common/io/Files.java
@@ -412,13 +412,20 @@ public static boolean equal(File file1, File file2) throws IOException {
    * <p>This method assumes that the temporary volume is writable, has free inodes and free blocks,
    * and that it will not be called thousands of times per second.
    *
+   * <p><b>Warning for Windows users:</b> This method is one of the Guava APIs known to <i>not</i>
+   * work under Windows. Note that <a href="https://github.com/google/guava/issues/2686">we do not
+   * run our CI under Windows</a>, <a href="https://github.com/google/guava/issues/2130">we know
+   * that some of our tests fail under Windows</a>, and <a
+   * href="https://guava.dev/#important-warnings">we warn about using some features of Guava under
+   * Windows</a>, especially I/O features, and that warning applies even to APIs whose documentation
+   * doesn't include individual warnings like this one.
+   *
    * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
    * java.nio.file.Files#createTempDirectory}.
    *
    * @return the newly-created directory
-   * @throws IllegalStateException if the directory could not be created
-   * @throws UnsupportedOperationException if the system does not support creating temporary
-   *     directories securely
+   * @throws IllegalStateException if the directory could not be created, such as if the system does
+   *     not support creating temporary directories securely
    * @deprecated For Android users, see the <a
    *     href="https://developer.android.com/training/data-storage" target="_blank">Data and File
    *     Storage overview</a> to select an appropriate temporary directory (perhaps {@code

diff --git a/android/guava/src/com/google/common/io/TempFileCreator.java b/android/guava/src/com/google/common/io/TempFileCreator.java
@@ -42,8 +42,7 @@ abstract class TempFileCreator {
 
   /**
    * @throws IllegalStateException if the directory could not be created (to implement the contract
-   *     of {@link Files#createTempDir()}
-   * @throws UnsupportedOperationException if the system does not support creating temporary
+   *     of {@link Files#createTempDir()}, such as if the system does not support creating temporary
    *     directories securely
    */
   abstract File createTempDir();

diff --git a/guava/src/com/google/common/io/FileBackedOutputStream.java b/guava/src/com/google/common/io/FileBackedOutputStream.java
@@ -58,6 +58,13 @@
  *
  * <p>This class is thread-safe.
  *
+ * <p><b>Warning for Windows users:</b> This class is one of the Guava APIs known to <i>not</i> work
+ * under Windows. Note that <a href="https://github.com/google/guava/issues/2686">we do not run our
+ * CI under Windows</a>, <a href="https://github.com/google/guava/issues/2130">we know that some of
+ * our tests fail under Windows</a>, and <a href="https://guava.dev/#important-warnings">we warn
+ * about using some features of Guava under Windows</a>, especially I/O features, and that warning
+ * applies even to APIs whose documentation doesn't include individual warnings like this one.
+ *
  * @author Chris Nokleberg
  * @since 1.0
  */

diff --git a/guava/src/com/google/common/io/Files.java b/guava/src/com/google/common/io/Files.java
@@ -412,13 +412,20 @@ public static boolean equal(File file1, File file2) throws IOException {
    * <p>This method assumes that the temporary volume is writable, has free inodes and free blocks,
    * and that it will not be called thousands of times per second.
    *
+   * <p><b>Warning for Windows users:</b> This method is one of the Guava APIs known to <i>not</i>
+   * work under Windows. Note that <a href="https://github.com/google/guava/issues/2686">we do not
+   * run our CI under Windows</a>, <a href="https://github.com/google/guava/issues/2130">we know
+   * that some of our tests fail under Windows</a>, and <a
+   * href="https://guava.dev/#important-warnings">we warn about using some features of Guava under
+   * Windows</a>, especially I/O features, and that warning applies even to APIs whose documentation
+   * doesn't include individual warnings like this one.
+   *
    * <p><b>{@link java.nio.file.Path} equivalent:</b> {@link
    * java.nio.file.Files#createTempDirectory}.
    *
    * @return the newly-created directory
-   * @throws IllegalStateException if the directory could not be created
-   * @throws UnsupportedOperationException if the system does not support creating temporary
-   *     directories securely
+   * @throws IllegalStateException if the directory could not be created, such as if the system does
+   *     not support creating temporary directories securely
    * @deprecated For Android users, see the <a
    *     href="https://developer.android.com/training/data-storage" target="_blank">Data and File
    *     Storage overview</a> to select an appropriate temporary directory (perhaps {@code

diff --git a/guava/src/com/google/common/io/TempFileCreator.java b/guava/src/com/google/common/io/TempFileCreator.java
@@ -42,8 +42,7 @@ abstract class TempFileCreator {
 
   /**
    * @throws IllegalStateException if the directory could not be created (to implement the contract
-   *     of {@link Files#createTempDir()}
-   * @throws UnsupportedOperationException if the system does not support creating temporary
+   *     of {@link Files#createTempDir()}, such as if the system does not support creating temporary
    *     directories securely
    */
   abstract File createTempDir();