From 828d9ee74e8aef4f192bd0c6079db20c28780cb1 Mon Sep 17 00:00:00 2001 From: "David P. Baker" Date: Thu, 6 Jan 2022 07:59:31 -0800 Subject: [PATCH] Remove `@Beta` from APIs in `Files`. Add `@InlineMe` where we can. Fixes https://github.com/google/guava/issues/3285. RELNOTES=`io`: Remove `@Beta` from APIs in `Files`. PiperOrigin-RevId: 420062384 --- .../guava/src/com/google/common/io/Files.java | 73 ++++++++----------- .../src/com/google/common/io/Resources.java | 2 - guava/src/com/google/common/io/Files.java | 73 ++++++++----------- guava/src/com/google/common/io/Resources.java | 2 - 4 files changed, 64 insertions(+), 86 deletions(-) diff --git a/android/guava/src/com/google/common/io/Files.java b/android/guava/src/com/google/common/io/Files.java index bf6289e90f25..ba5528ff81dd 100644 --- a/android/guava/src/com/google/common/io/Files.java +++ b/android/guava/src/com/google/common/io/Files.java @@ -32,6 +32,7 @@ import com.google.common.hash.HashCode; import com.google.common.hash.HashFunction; import com.google.errorprone.annotations.CanIgnoreReturnValue; +import com.google.errorprone.annotations.InlineMe; import java.io.BufferedReader; import java.io.BufferedWriter; import java.io.File; @@ -85,7 +86,6 @@ private Files() {} * helpful predefined constants * @return the buffered reader */ - @Beta public static BufferedReader newReader(File file, Charset charset) throws FileNotFoundException { checkNotNull(file); checkNotNull(charset); @@ -104,7 +104,6 @@ public static BufferedReader newReader(File file, Charset charset) throws FileNo * helpful predefined constants * @return the buffered writer */ - @Beta public static BufferedWriter newWriter(File file, Charset charset) throws FileNotFoundException { checkNotNull(file); checkNotNull(charset); @@ -235,7 +234,6 @@ public static CharSink asCharSink(File file, Charset charset, FileWriteMode... m * (2^31 - 1) * @throws IOException if an I/O error occurs */ - @Beta public static byte[] toByteArray(File file) throws IOException { return asByteSource(file).read(); } @@ -248,11 +246,12 @@ public static byte[] toByteArray(File file) throws IOException { * helpful predefined constants * @return a string containing all the characters from the file * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).read()}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).read()}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).read()", + imports = "com.google.common.io.Files") public static String toString(File file, Charset charset) throws IOException { return asCharSource(file, charset).read(); } @@ -267,7 +266,6 @@ public static String toString(File file, Charset charset) throws IOException { * @param to the destination file * @throws IOException if an I/O error occurs */ - @Beta public static void write(byte[] from, File to) throws IOException { asByteSink(to).write(from); } @@ -280,11 +278,12 @@ public static void write(byte[] from, File to) throws IOException { * @param charset the charset used to encode the output stream; see {@link StandardCharsets} for * helpful predefined constants * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSink(to, charset).write(from)}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asCharSink(to, charset).write(from)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSink(to, charset).write(from)", + imports = "com.google.common.io.Files") public static void write(CharSequence from, File to, Charset charset) throws IOException { asCharSink(to, charset).write(from); } @@ -299,7 +298,6 @@ public static void write(CharSequence from, File to, Charset charset) throws IOE * @param to the output stream * @throws IOException if an I/O error occurs */ - @Beta public static void copy(File from, OutputStream to) throws IOException { asByteSource(from).copyTo(to); } @@ -323,7 +321,6 @@ public static void copy(File from, OutputStream to) throws IOException { * @throws IOException if an I/O error occurs * @throws IllegalArgumentException if {@code from.equals(to)} */ - @Beta public static void copy(File from, File to) throws IOException { checkArgument(!from.equals(to), "Source %s and destination %s must be different", from, to); asByteSource(from).copyTo(asByteSink(to)); @@ -337,11 +334,12 @@ public static void copy(File from, File to) throws IOException { * helpful predefined constants * @param to the appendable object * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(from, charset).copyTo(to)}. This method is scheduled to - * be removed in October 2019. + * @deprecated Prefer {@code asCharSource(from, charset).copyTo(to)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(from, charset).copyTo(to)", + imports = "com.google.common.io.Files") public static void copy(File from, Charset charset, Appendable to) throws IOException { asCharSource(from, charset).copyTo(to); @@ -358,8 +356,10 @@ static void copy(File from, Charset charset, Appendable to) throws IOException { * @deprecated Prefer {@code asCharSink(to, charset, FileWriteMode.APPEND).write(from)}. This * method is scheduled to be removed in October 2019. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSink(to, charset, FileWriteMode.APPEND).write(from)", + imports = {"com.google.common.io.FileWriteMode", "com.google.common.io.Files"}) public static void append(CharSequence from, File to, Charset charset) throws IOException { asCharSink(to, charset, FileWriteMode.APPEND).write(from); @@ -370,7 +370,6 @@ static void append(CharSequence from, File to, Charset charset) throws IOExcepti * * @throws IOException if an I/O error occurs */ - @Beta public static boolean equal(File file1, File file2) throws IOException { checkNotNull(file1); checkNotNull(file2); @@ -452,7 +451,6 @@ public static File createTempDir() { * @param file the file to create or update * @throws IOException if an I/O error occurs */ - @Beta @SuppressWarnings("GoodTime") // reading system time without TimeSource public static void touch(File file) throws IOException { checkNotNull(file); @@ -470,7 +468,6 @@ public static void touch(File file) throws IOException { * directories of the specified file could not be created. * @since 4.0 */ - @Beta public static void createParentDirs(File file) throws IOException { checkNotNull(file); File parent = file.getCanonicalFile().getParentFile(); @@ -501,7 +498,6 @@ public static void createParentDirs(File file) throws IOException { * @throws IOException if an I/O error occurs * @throws IllegalArgumentException if {@code from.equals(to)} */ - @Beta public static void move(File from, File to) throws IOException { checkNotNull(from); checkNotNull(to); @@ -527,11 +523,12 @@ public static void move(File from, File to) throws IOException { * helpful predefined constants * @return the first line, or null if the file is empty * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).readFirstLine()}. This method is - * scheduled to be removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).readFirstLine()}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).readFirstLine()", + imports = "com.google.common.io.Files") @CheckForNull public static String readFirstLine(File file, Charset charset) throws IOException { @@ -554,7 +551,6 @@ static String readFirstLine(File file, Charset charset) throws IOException { * @return a mutable {@link List} containing all the lines * @throws IOException if an I/O error occurs */ - @Beta public static List readLines(File file, Charset charset) throws IOException { // don't use asCharSource(file, charset).readLines() because that returns // an immutable list, which would change the behavior of this method @@ -586,11 +582,12 @@ public List getResult() { * @param callback the {@link LineProcessor} to use to handle the lines * @return the output of processing the lines * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).readLines(callback)}. This method is - * scheduled to be removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).readLines(callback)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).readLines(callback)", + imports = "com.google.common.io.Files") @CanIgnoreReturnValue // some processors won't return a useful result @ParametricNullness public @@ -608,11 +605,12 @@ public List getResult() { * @param processor the object to which the bytes of the file are passed. * @return the result of the byte processor * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asByteSource(file).read(processor)}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asByteSource(file).read(processor)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asByteSource(file).read(processor)", + imports = "com.google.common.io.Files") @CanIgnoreReturnValue // some processors won't return a useful result @ParametricNullness public @@ -629,11 +627,12 @@ public List getResult() { * @return the {@link HashCode} of all of the bytes in the file * @throws IOException if an I/O error occurs * @since 12.0 - * @deprecated Prefer {@code asByteSource(file).hash(hashFunction)}. This method is scheduled to - * be removed in October 2019. + * @deprecated Prefer {@code asByteSource(file).hash(hashFunction)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asByteSource(file).hash(hashFunction)", + imports = "com.google.common.io.Files") public static HashCode hash(File file, HashFunction hashFunction) throws IOException { return asByteSource(file).hash(hashFunction); @@ -654,7 +653,6 @@ static HashCode hash(File file, HashFunction hashFunction) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file) throws IOException { checkNotNull(file); return map(file, MapMode.READ_ONLY); @@ -677,7 +675,6 @@ public static MappedByteBuffer map(File file) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file, MapMode mode) throws IOException { return mapInternal(file, mode, -1); } @@ -701,7 +698,6 @@ public static MappedByteBuffer map(File file, MapMode mode) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file, MapMode mode, long size) throws IOException { checkArgument(size >= 0, "size (%s) may not be negative", size); return mapInternal(file, mode, size); @@ -745,7 +741,6 @@ private static MappedByteBuffer mapInternal(File file, MapMode mode, long size) * * @since 11.0 */ - @Beta public static String simplifyPath(String pathname) { checkNotNull(pathname); if (pathname.length() == 0) { @@ -806,7 +801,6 @@ public static String simplifyPath(String pathname) { * * @since 11.0 */ - @Beta public static String getFileExtension(String fullName) { checkNotNull(fullName); String fileName = new File(fullName).getName(); @@ -824,7 +818,6 @@ public static String getFileExtension(String fullName) { * @return The file name without its path or extension. * @since 14.0 */ - @Beta public static String getNameWithoutExtension(String file) { checkNotNull(file); String fileName = new File(file).getName(); @@ -880,7 +873,6 @@ public Iterable successors(File file) { * * @since 15.0 */ - @Beta public static Predicate isDirectory() { return FilePredicate.IS_DIRECTORY; } @@ -890,7 +882,6 @@ public static Predicate isDirectory() { * * @since 15.0 */ - @Beta public static Predicate isFile() { return FilePredicate.IS_FILE; } diff --git a/android/guava/src/com/google/common/io/Resources.java b/android/guava/src/com/google/common/io/Resources.java index ae3233408b35..d1e37070a91c 100644 --- a/android/guava/src/com/google/common/io/Resources.java +++ b/android/guava/src/com/google/common/io/Resources.java @@ -17,7 +17,6 @@ import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; -import com.google.common.annotations.Beta; import com.google.common.annotations.GwtIncompatible; import com.google.common.base.Charsets; import com.google.common.base.MoreObjects; @@ -41,7 +40,6 @@ * @author Colin Decker * @since 1.0 */ -@Beta @GwtIncompatible @ElementTypesAreNonnullByDefault public final class Resources { diff --git a/guava/src/com/google/common/io/Files.java b/guava/src/com/google/common/io/Files.java index bf6289e90f25..ba5528ff81dd 100644 --- a/guava/src/com/google/common/io/Files.java +++ b/guava/src/com/google/common/io/Files.java @@ -32,6 +32,7 @@ import com.google.common.hash.HashCode; import com.google.common.hash.HashFunction; import com.google.errorprone.annotations.CanIgnoreReturnValue; +import com.google.errorprone.annotations.InlineMe; import java.io.BufferedReader; import java.io.BufferedWriter; import java.io.File; @@ -85,7 +86,6 @@ private Files() {} * helpful predefined constants * @return the buffered reader */ - @Beta public static BufferedReader newReader(File file, Charset charset) throws FileNotFoundException { checkNotNull(file); checkNotNull(charset); @@ -104,7 +104,6 @@ public static BufferedReader newReader(File file, Charset charset) throws FileNo * helpful predefined constants * @return the buffered writer */ - @Beta public static BufferedWriter newWriter(File file, Charset charset) throws FileNotFoundException { checkNotNull(file); checkNotNull(charset); @@ -235,7 +234,6 @@ public static CharSink asCharSink(File file, Charset charset, FileWriteMode... m * (2^31 - 1) * @throws IOException if an I/O error occurs */ - @Beta public static byte[] toByteArray(File file) throws IOException { return asByteSource(file).read(); } @@ -248,11 +246,12 @@ public static byte[] toByteArray(File file) throws IOException { * helpful predefined constants * @return a string containing all the characters from the file * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).read()}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).read()}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).read()", + imports = "com.google.common.io.Files") public static String toString(File file, Charset charset) throws IOException { return asCharSource(file, charset).read(); } @@ -267,7 +266,6 @@ public static String toString(File file, Charset charset) throws IOException { * @param to the destination file * @throws IOException if an I/O error occurs */ - @Beta public static void write(byte[] from, File to) throws IOException { asByteSink(to).write(from); } @@ -280,11 +278,12 @@ public static void write(byte[] from, File to) throws IOException { * @param charset the charset used to encode the output stream; see {@link StandardCharsets} for * helpful predefined constants * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSink(to, charset).write(from)}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asCharSink(to, charset).write(from)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSink(to, charset).write(from)", + imports = "com.google.common.io.Files") public static void write(CharSequence from, File to, Charset charset) throws IOException { asCharSink(to, charset).write(from); } @@ -299,7 +298,6 @@ public static void write(CharSequence from, File to, Charset charset) throws IOE * @param to the output stream * @throws IOException if an I/O error occurs */ - @Beta public static void copy(File from, OutputStream to) throws IOException { asByteSource(from).copyTo(to); } @@ -323,7 +321,6 @@ public static void copy(File from, OutputStream to) throws IOException { * @throws IOException if an I/O error occurs * @throws IllegalArgumentException if {@code from.equals(to)} */ - @Beta public static void copy(File from, File to) throws IOException { checkArgument(!from.equals(to), "Source %s and destination %s must be different", from, to); asByteSource(from).copyTo(asByteSink(to)); @@ -337,11 +334,12 @@ public static void copy(File from, File to) throws IOException { * helpful predefined constants * @param to the appendable object * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(from, charset).copyTo(to)}. This method is scheduled to - * be removed in October 2019. + * @deprecated Prefer {@code asCharSource(from, charset).copyTo(to)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(from, charset).copyTo(to)", + imports = "com.google.common.io.Files") public static void copy(File from, Charset charset, Appendable to) throws IOException { asCharSource(from, charset).copyTo(to); @@ -358,8 +356,10 @@ static void copy(File from, Charset charset, Appendable to) throws IOException { * @deprecated Prefer {@code asCharSink(to, charset, FileWriteMode.APPEND).write(from)}. This * method is scheduled to be removed in October 2019. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSink(to, charset, FileWriteMode.APPEND).write(from)", + imports = {"com.google.common.io.FileWriteMode", "com.google.common.io.Files"}) public static void append(CharSequence from, File to, Charset charset) throws IOException { asCharSink(to, charset, FileWriteMode.APPEND).write(from); @@ -370,7 +370,6 @@ static void append(CharSequence from, File to, Charset charset) throws IOExcepti * * @throws IOException if an I/O error occurs */ - @Beta public static boolean equal(File file1, File file2) throws IOException { checkNotNull(file1); checkNotNull(file2); @@ -452,7 +451,6 @@ public static File createTempDir() { * @param file the file to create or update * @throws IOException if an I/O error occurs */ - @Beta @SuppressWarnings("GoodTime") // reading system time without TimeSource public static void touch(File file) throws IOException { checkNotNull(file); @@ -470,7 +468,6 @@ public static void touch(File file) throws IOException { * directories of the specified file could not be created. * @since 4.0 */ - @Beta public static void createParentDirs(File file) throws IOException { checkNotNull(file); File parent = file.getCanonicalFile().getParentFile(); @@ -501,7 +498,6 @@ public static void createParentDirs(File file) throws IOException { * @throws IOException if an I/O error occurs * @throws IllegalArgumentException if {@code from.equals(to)} */ - @Beta public static void move(File from, File to) throws IOException { checkNotNull(from); checkNotNull(to); @@ -527,11 +523,12 @@ public static void move(File from, File to) throws IOException { * helpful predefined constants * @return the first line, or null if the file is empty * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).readFirstLine()}. This method is - * scheduled to be removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).readFirstLine()}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).readFirstLine()", + imports = "com.google.common.io.Files") @CheckForNull public static String readFirstLine(File file, Charset charset) throws IOException { @@ -554,7 +551,6 @@ static String readFirstLine(File file, Charset charset) throws IOException { * @return a mutable {@link List} containing all the lines * @throws IOException if an I/O error occurs */ - @Beta public static List readLines(File file, Charset charset) throws IOException { // don't use asCharSource(file, charset).readLines() because that returns // an immutable list, which would change the behavior of this method @@ -586,11 +582,12 @@ public List getResult() { * @param callback the {@link LineProcessor} to use to handle the lines * @return the output of processing the lines * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asCharSource(file, charset).readLines(callback)}. This method is - * scheduled to be removed in October 2019. + * @deprecated Prefer {@code asCharSource(file, charset).readLines(callback)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asCharSource(file, charset).readLines(callback)", + imports = "com.google.common.io.Files") @CanIgnoreReturnValue // some processors won't return a useful result @ParametricNullness public @@ -608,11 +605,12 @@ public List getResult() { * @param processor the object to which the bytes of the file are passed. * @return the result of the byte processor * @throws IOException if an I/O error occurs - * @deprecated Prefer {@code asByteSource(file).read(processor)}. This method is scheduled to be - * removed in October 2019. + * @deprecated Prefer {@code asByteSource(file).read(processor)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asByteSource(file).read(processor)", + imports = "com.google.common.io.Files") @CanIgnoreReturnValue // some processors won't return a useful result @ParametricNullness public @@ -629,11 +627,12 @@ public List getResult() { * @return the {@link HashCode} of all of the bytes in the file * @throws IOException if an I/O error occurs * @since 12.0 - * @deprecated Prefer {@code asByteSource(file).hash(hashFunction)}. This method is scheduled to - * be removed in October 2019. + * @deprecated Prefer {@code asByteSource(file).hash(hashFunction)}. */ - @Beta @Deprecated + @InlineMe( + replacement = "Files.asByteSource(file).hash(hashFunction)", + imports = "com.google.common.io.Files") public static HashCode hash(File file, HashFunction hashFunction) throws IOException { return asByteSource(file).hash(hashFunction); @@ -654,7 +653,6 @@ static HashCode hash(File file, HashFunction hashFunction) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file) throws IOException { checkNotNull(file); return map(file, MapMode.READ_ONLY); @@ -677,7 +675,6 @@ public static MappedByteBuffer map(File file) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file, MapMode mode) throws IOException { return mapInternal(file, mode, -1); } @@ -701,7 +698,6 @@ public static MappedByteBuffer map(File file, MapMode mode) throws IOException { * @see FileChannel#map(MapMode, long, long) * @since 2.0 */ - @Beta public static MappedByteBuffer map(File file, MapMode mode, long size) throws IOException { checkArgument(size >= 0, "size (%s) may not be negative", size); return mapInternal(file, mode, size); @@ -745,7 +741,6 @@ private static MappedByteBuffer mapInternal(File file, MapMode mode, long size) * * @since 11.0 */ - @Beta public static String simplifyPath(String pathname) { checkNotNull(pathname); if (pathname.length() == 0) { @@ -806,7 +801,6 @@ public static String simplifyPath(String pathname) { * * @since 11.0 */ - @Beta public static String getFileExtension(String fullName) { checkNotNull(fullName); String fileName = new File(fullName).getName(); @@ -824,7 +818,6 @@ public static String getFileExtension(String fullName) { * @return The file name without its path or extension. * @since 14.0 */ - @Beta public static String getNameWithoutExtension(String file) { checkNotNull(file); String fileName = new File(file).getName(); @@ -880,7 +873,6 @@ public Iterable successors(File file) { * * @since 15.0 */ - @Beta public static Predicate isDirectory() { return FilePredicate.IS_DIRECTORY; } @@ -890,7 +882,6 @@ public static Predicate isDirectory() { * * @since 15.0 */ - @Beta public static Predicate isFile() { return FilePredicate.IS_FILE; } diff --git a/guava/src/com/google/common/io/Resources.java b/guava/src/com/google/common/io/Resources.java index ae3233408b35..d1e37070a91c 100644 --- a/guava/src/com/google/common/io/Resources.java +++ b/guava/src/com/google/common/io/Resources.java @@ -17,7 +17,6 @@ import static com.google.common.base.Preconditions.checkArgument; import static com.google.common.base.Preconditions.checkNotNull; -import com.google.common.annotations.Beta; import com.google.common.annotations.GwtIncompatible; import com.google.common.base.Charsets; import com.google.common.base.MoreObjects; @@ -41,7 +40,6 @@ * @author Colin Decker * @since 1.0 */ -@Beta @GwtIncompatible @ElementTypesAreNonnullByDefault public final class Resources {