archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 06:45:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8307409: Refactor usage examples to use @snippet in the java.nio packages

Browse source 
Reviewed-by: alanb, rriggs
This commit is contained in:
Brian Burkhalter 2023-05-12 15:17:22 +00:00
parent e512a20679
commit 9fa8b9a4a6
33 changed files with 433 additions and 386 deletions
Download patch file Download diff file Expand all files Collapse all files

96
src/java.base/share/classes/java/nio/file/Files.java
View file

@ -179,7 +179,7 @@ public final class Files {
* regular-file} to a size of {@code 0} if it exists.
*
* <p> <b>Usage Examples:</b>
* <pre>
* {@snippet lang=java :
* Path path = ...
*
* // truncate and overwrite an existing file, or create the file if
@ -194,7 +194,7 @@ public final class Files {
*
* // always create new file, failing if it already exists
* out = Files.newOutputStream(path, CREATE_NEW);
* </pre>
* }
*
* @param path
* the path to the file to open or create
@ -320,7 +320,7 @@ public final class Files {
* is a {@link java.nio.channels.FileChannel}.
*
* <p> <b>Usage Examples:</b>
* <pre>{@code
* {@snippet lang=java :
* Path path = ...
*
* // open file for reading
@ -334,7 +334,7 @@ public final class Files {
* FileAttribute<Set<PosixFilePermission>> perms = ...
* SeekableByteChannel sbc =
* Files.newByteChannel(path, EnumSet.of(CREATE_NEW,READ,WRITE), perms);
* }</pre>
* }
*
* @param path
* the path to the file to open or create
@ -493,12 +493,12 @@ public final class Files {
*
* <p> For example, suppose we want to iterate over the files ending with
* ".java" in a directory:
* <pre>
* {@snippet lang=java :
* Path dir = ...
* try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir, "*.java")) {
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.java")) {
* :
* }
* </pre>
* }
*
* <p> The globbing pattern is specified by the {@link
* FileSystem#getPathMatcher getPathMatcher} method.
@ -577,17 +577,17 @@ public final class Files {
* <p> <b>Usage Example:</b>
* Suppose we want to iterate over the files in a directory that are
* larger than 8K.
* <pre>
* DirectoryStream.Filter&lt;Path&gt; filter = new DirectoryStream.Filter&lt;Path&gt;() {
* {@snippet lang=java :
* DirectoryStream.Filter<Path> filter = new DirectoryStream.Filter<Path>() {
* public boolean accept(Path file) throws IOException {
* return (Files.size(file) &gt; 8192L);
* return (Files.size(file) > 8192L);
* }
* };
* Path dir = ...
* try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir, filter)) {
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, filter)) {
* :
* }
* </pre>
* }
*
* @param dir
* the path to the directory
@ -1257,11 +1257,11 @@ public final class Files {
* <p> <b>Usage Example:</b>
* Suppose we want to copy a file into a directory, giving it the same file
* name as the source file:
* <pre>
* {@snippet lang=java :
* Path source = ...
* Path newdir = ...
* Files.copy(source, newdir.resolve(source.getFileName());
* </pre>
* }
*
* @param source
* the path to the file to copy
@ -1375,18 +1375,18 @@ public final class Files {
* <p> <b>Usage Examples:</b>
* Suppose we want to rename a file to "newname", keeping the file in the
* same directory:
* <pre>
* {@snippet lang=java :
* Path source = ...
* Files.move(source, source.resolveSibling("newname"));
* </pre>
* }
* Alternatively, suppose we want to move a file to new directory, keeping
* the same file name, and replacing any existing file of that name in the
* directory:
* <pre>
* {@snippet lang=java :
* Path source = ...
* Path newdir = ...
* Files.move(source, newdir.resolve(source.getFileName()), REPLACE_EXISTING);
* </pre>
* }
*
* @param source
* the path to the file to move
@ -1761,14 +1761,14 @@ public final class Files {
*
* <p> <b>Usage Example:</b>
* Suppose we want read or set a file's ACL, if supported:
* <pre>
* {@snippet lang=java :
* Path path = ...
* AclFileAttributeView view = Files.getFileAttributeView(path, AclFileAttributeView.class);
* if (view != null) {
* List&lt;AclEntry&gt; acl = view.getAcl();
* List<AclEntry> acl = view.getAcl();
* :
* }
* </pre>
* }
*
* @param <V>
* The {@code FileAttributeView} type
@ -1810,16 +1810,16 @@ public final class Files {
*
* <p> <b>Usage Example:</b>
* Suppose we want to read a file's attributes in bulk:
* <pre>
* Path path = ...
* BasicFileAttributes attrs = Files.readAttributes(path, BasicFileAttributes.class);
* </pre>
* {@snippet lang=java :
* Path path = ...
* BasicFileAttributes attrs = Files.readAttributes(path, BasicFileAttributes.class);
* }
* Alternatively, suppose we want to read file's POSIX attributes without
* following symbolic links:
* <pre>
* PosixFileAttributes attrs =
* Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
* </pre>
* {@snippet lang=java :
* PosixFileAttributes attrs =
* Files.readAttributes(path, PosixFileAttributes.class, NOFOLLOW_LINKS);
* }
*
* @param <A>
* The {@code BasicFileAttributes} type
@ -1878,10 +1878,10 @@ public final class Files {
*
* <p> <b>Usage Example:</b>
* Suppose we want to set the DOS "hidden" attribute:
* <pre>
* Path path = ...
* Files.setAttribute(path, "dos:hidden", true);
* </pre>
* {@snippet lang=java :
* Path path = ...
* Files.setAttribute(path, "dos:hidden", true);
* }
*
* @param path
* the path to the file
@ -1947,10 +1947,10 @@ public final class Files {
* <p> <b>Usage Example:</b>
* Suppose we require the user ID of the file owner on a system that
* supports a "{@code unix}" view:
* <pre>
* Path path = ...
* int uid = (Integer)Files.getAttribute(path, "unix:uid");
* </pre>
* {@snippet lang=java :
* Path path = ...
* int uid = (Integer)Files.getAttribute(path, "unix:uid");
* }
*
* @param path
* the path to the file
@ -2212,13 +2212,13 @@ public final class Files {
*
* <p> <b>Usage Example:</b>
* Suppose we want to make "joe" the owner of a file:
* <pre>
* {@snippet lang=java :
* Path path = ...
* UserPrincipalLookupService lookupService =
* provider(path).getUserPrincipalLookupService();
* UserPrincipal joe = lookupService.lookupPrincipalByName("joe");
* Files.setOwner(path, joe);
* </pre>
* }
*
* @param path
* The path to the file
@ -2406,11 +2406,11 @@ public final class Files {
*
* <p> <b>Usage Example:</b>
* Suppose we want to set the last modified time to the current time:
* <pre>
* Path path = ...
* FileTime now = FileTime.fromMillis(System.currentTimeMillis());
* Files.setLastModifiedTime(path, now);
* </pre>
* {@snippet lang=java :
* Path path = ...
* FileTime now = FileTime.fromMillis(System.currentTimeMillis());
* Files.setLastModifiedTime(path, now);
* }
*
* @param path
* the path to the file
@ -3063,13 +3063,13 @@ public final class Files {
*
* <p> <b>Usage example</b>: Suppose we want to capture a web page and save
* it to a file:
* <pre>
* {@snippet lang=java :
* Path path = ...
* URI u = URI.create("http://www.example.com/");
* try (InputStream in = u.toURL().openStream()) {
* Files.copy(in, path);
* }
* </pre>
* }
*
* @param in
* the input stream to read from
@ -3449,11 +3449,11 @@ public final class Files {
* <p> <b>Usage example</b>: By default the method creates a new file or
* overwrites an existing file. Suppose you instead want to append bytes
* to an existing file:
* <pre>
* {@snippet lang=java :
* Path path = ...
* byte[] bytes = ...
* Files.write(path, bytes, StandardOpenOption.APPEND);
* </pre>
* }
*
* @param path
* the path to the file