archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-26 22:34:27 +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

46
src/java.base/share/classes/java/nio/file/DirectoryStream.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -52,14 +52,14 @@ import java.io.IOException;
* resources associated with the stream. Failure to close the stream may result
* in a resource leak. The try-with-resources statement provides a useful
* construct to ensure that the stream is closed:
* <pre>
* Path dir = ...
* try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir)) {
* for (Path entry: stream) {
* ...
* }
* }
* </pre>
* {@snippet lang=java :
* Path dir = ...
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir)) {
* for (Path entry: stream) {
* ...
* }
* }
* }
*
* <p> Once a directory stream is closed, then further access to the directory,
* using the {@code Iterator}, behaves as if the end of stream has been reached.
@ -95,20 +95,20 @@ import java.io.IOException;
* <p> <b>Usage Examples:</b>
* Suppose we want a list of the source files in a directory. This example uses
* both the for-each and try-with-resources constructs.
* <pre>
* List&lt;Path&gt; listSourceFiles(Path dir) throws IOException {
* List&lt;Path&gt; result = new ArrayList&lt;&gt;();
* try (DirectoryStream&lt;Path&gt; stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
* for (Path entry: stream) {
* result.add(entry);
* }
* } catch (DirectoryIteratorException ex) {
* // I/O error encountered during the iteration, the cause is an IOException
* throw ex.getCause();
* }
* return result;
* }
* </pre>
* {@snippet lang=java :
* List<Path> listSourceFiles(Path dir) throws IOException {
* List<Path> result = new ArrayList<>();
* try (DirectoryStream<Path> stream = Files.newDirectoryStream(dir, "*.{c,h,cpp,hpp,java}")) {
* for (Path entry: stream) {
* result.add(entry);
* }
* } catch (DirectoryIteratorException ex) {
* // I/O error encountered during the iteration, the cause is an IOException
* throw ex.getCause();
* }
* return result;
* }
* }
* @param <T> The type of element returned by the iterator
*
* @since 1.7

8
src/java.base/share/classes/java/nio/file/FileStore.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -231,9 +231,9 @@ public abstract class FileStore {
* <p> <b>Usage Example:</b>
* Suppose we want to know if ZFS compression is enabled (assuming the "zfs"
* view is supported):
* <pre>
* boolean compression = (Boolean)fs.getAttribute("zfs:compression");
* </pre>
* {@snippet lang=java :
* boolean compression = (Boolean)fs.getAttribute("zfs:compression");
* }
*
* @param attribute
* the attribute to read

10
src/java.base/share/classes/java/nio/file/FileSystem.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -212,14 +212,14 @@ public abstract class FileSystem
*
* <p> <b>Usage Example:</b>
* Suppose we want to print the space usage for all file stores:
* <pre>
* {@snippet lang=java :
* for (FileStore store: FileSystems.getDefault().getFileStores()) {
* long total = store.getTotalSpace() / 1024;
* long used = (store.getTotalSpace() - store.getUnallocatedSpace()) / 1024;
* long avail = store.getUsableSpace() / 1024;
* System.out.format("%-20s %12d %12d %12d%n", store, total, used, avail);
* }
* </pre>
* }
*
* @return An object to iterate over the backing file stores
*/
@ -444,10 +444,10 @@ public abstract class FileSystem
*
* <p> <b>Usage Example:</b>
* Suppose we want to make "joe" the owner of a file:
* <pre>
* {@snippet lang=java :
* UserPrincipalLookupService lookupService = FileSystems.getDefault().getUserPrincipalLookupService();
* Files.setOwner(path, lookupService.lookupPrincipalByName("joe"));
* </pre>
* }
*
* @throws UnsupportedOperationException
* If this {@code FileSystem} does not does have a lookup service

10
src/java.base/share/classes/java/nio/file/FileSystems.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -255,10 +255,10 @@ public final class FileSystems {
* <p> <b>Usage Example:</b>
* Suppose there is a provider identified by the scheme {@code "memory"}
* installed:
* <pre>
* FileSystem fs = FileSystems.newFileSystem(URI.create("memory:///?name=logfs"),
* Map.of("capacity", "16G", "blockSize", "4k"));
* </pre>
* {@snippet lang=java :
* FileSystem fs = FileSystems.newFileSystem(URI.create("memory:///?name=logfs"),
* Map.of("capacity", "16G", "blockSize", "4k"));
* }
*
* @param uri
* the URI identifying the file system

6
src/java.base/share/classes/java/nio/file/FileTreeIterator.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2013, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2013, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -36,7 +36,7 @@ import java.nio.file.FileTreeWalker.Event;
/**
* An {@code Iterator} to iterate over the nodes of a file tree.
*
* <pre>{@code
* {@snippet lang=java :
* try (FileTreeIterator iterator = new FileTreeIterator(start, maxDepth, options)) {
* while (iterator.hasNext()) {
* Event ev = iterator.next();
@ -44,7 +44,7 @@ import java.nio.file.FileTreeWalker.Event;
* BasicFileAttributes attrs = ev.attributes();
* }
* }
* }</pre>
* }
*/
class FileTreeIterator implements Iterator<Event>, Closeable {

6
src/java.base/share/classes/java/nio/file/FileTreeWalker.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -37,7 +37,7 @@ import sun.nio.fs.BasicFileAttributesHolder;
* Walks a file tree, generating a sequence of events corresponding to the files
* in the tree.
*
* <pre>{@code
* {@snippet lang=java :
* Path top = ...
* Set<FileVisitOption> options = ...
* int maxDepth = ...
@ -49,7 +49,7 @@ import sun.nio.fs.BasicFileAttributesHolder;
* ev = walker.next();
* } while (ev != null);
* }
* }</pre>
* }
*
* @see Files#walkFileTree
*/

22
src/java.base/share/classes/java/nio/file/FileVisitor.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -36,17 +36,17 @@ import java.io.IOException;
* <p> <b>Usage Examples:</b>
* Suppose we want to delete a file tree. In that case, each directory should
* be deleted after the entries in the directory are deleted.
* <pre>
* {@snippet lang=java :
* Path start = ...
* Files.walkFileTree(start, new SimpleFileVisitor&lt;Path&gt;() {
* &#64;Override
* Files.walkFileTree(start, new SimpleFileVisitor<Path>() {
* @Override
* public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
* throws IOException
* {
* Files.delete(file);
* return FileVisitResult.CONTINUE;
* }
* &#64;Override
* @Override
* public FileVisitResult postVisitDirectory(Path dir, IOException e)
* throws IOException
* {
@ -59,17 +59,17 @@ import java.io.IOException;
* }
* }
* });
* </pre>
* }
* <p> Furthermore, suppose we want to copy a file tree to a target location.
* In that case, symbolic links should be followed and the target directory
* should be created before the entries in the directory are copied.
* <pre>
* {@snippet lang=java :
* final Path source = ...
* final Path target = ...
*
* Files.walkFileTree(source, EnumSet.of(FileVisitOption.FOLLOW_LINKS), Integer.MAX_VALUE,
* new SimpleFileVisitor&lt;Path&gt;() {
* &#64;Override
* new SimpleFileVisitor<Path>() {
* @Override
* public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs)
* throws IOException
* {
@ -82,7 +82,7 @@ import java.io.IOException;
* }
* return CONTINUE;
* }
* &#64;Override
* @Override
* public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
* throws IOException
* {
@ -90,7 +90,7 @@ import java.io.IOException;
* return CONTINUE;
* }
* });
* </pre>
* }
* @param <T> the type of file/directory
*
* @since 1.7

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

55
src/java.base/share/classes/java/nio/file/Path.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -73,10 +73,10 @@ import java.util.Objects;
* java.io.BufferedReader} to read text from a file "{@code access.log}". The
* file is located in a directory "{@code logs}" relative to the current working
* directory and is UTF-8 encoded.
* <pre>
* {@snippet lang=java :
* Path path = FileSystems.getDefault().getPath("logs", "access.log");
* BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
* </pre>
* }
*
* <a id="interop"></a><h2>Interoperability</h2>
* <p> Paths associated with the default {@link
@ -125,10 +125,10 @@ public interface Path
* utility of the calling code. Hence it should not be used in library code
* intended for flexible reuse. A more flexible alternative is to use an
* existing {@code Path} instance as an anchor, such as:
* <pre>{@code
* {@snippet lang=java :
* Path dir = ...
* Path path = dir.resolve("file");
* }</pre>
* }
*
* @param first
* the path string or initial part of the path string
@ -266,9 +266,9 @@ public interface Path
*
* <p> If this path has more than one element, and no root component, then
* this method is equivalent to evaluating the expression:
* <blockquote><pre>
* subpath(0,&nbsp;getNameCount()-1);
* </pre></blockquote>
* {@snippet lang=java :
* subpath(0, getNameCount()-1);
* }
*
* @return a path representing the path's parent
*/
@ -363,9 +363,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* startsWith(getFileSystem().getPath(other));
* }</pre>
* }
*
* @param other
* the given path string
@ -419,9 +419,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* endsWith(getFileSystem().getPath(other));
* }</pre>
* }
*
* @param other
* the given path string
@ -498,9 +498,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* resolve(getFileSystem().getPath(other));
* }</pre>
* }
*
* @param other
* the path string to resolve against this path
@ -530,9 +530,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* (getParent() == null) ? other : getParent().resolve(other);
* }</pre>
* }
* unless {@code other == null}, in which case a
* {@code NullPointerException} is thrown.
*
@ -557,9 +557,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* resolveSibling(getFileSystem().getPath(other));
* }</pre>
* }
*
* @param other
* the path string to resolve against this path's parent
@ -753,9 +753,9 @@ public interface Path
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* new File(toString());
* }</pre>
* }
* if the {@code FileSystem} which created this {@code Path} is the default
* file system; otherwise an {@code UnsupportedOperationException} is
* thrown.
@ -845,25 +845,26 @@ public interface Path
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* watchable.{@link #register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) register}(watcher, events, new WatchEvent.Modifier[0]);
* </pre>
* {@snippet lang=java :
* // @link substring="register" target="Watchable#register" :
* register(watcher, events, new WatchEvent.Modifier[0]);
* }
*
* <p> <b>Usage Example:</b>
* Suppose we wish to register a directory for entry create, delete, and modify
* events:
* <pre>
* {@snippet lang=java :
* Path dir = ...
* WatchService watcher = ...
*
* WatchKey key = dir.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);
* </pre>
* }
*
* @implSpec
* The default implementation is equivalent for this path to:
* <pre>{@code
* {@snippet lang=java :
* register(watcher, events, new WatchEvent.Modifier[0]);
* }</pre>
* }
*
* @param watcher
* The watch service to which this object is to be registered

8
src/java.base/share/classes/java/nio/file/WatchKey.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -54,13 +54,13 @@ import java.util.List;
* created, a watch key has no pending events. Typically events are retrieved
* when the key is in the signalled state leading to the following idiom:
*
* <pre>
* {@snippet lang=java :
* for (;;) {
* // retrieve key
* WatchKey key = watcher.take();
*
* // process events
* for (WatchEvent&lt;?&gt; event: key.pollEvents()) {
* for (WatchEvent<?> event: key.pollEvents()) {
* :
* }
*
@ -70,7 +70,7 @@ import java.util.List;
* // object no longer registered
* }
* }
* </pre>
* }
*
* <p> Watch keys are safe for use by multiple concurrent threads. Where there
* are several threads retrieving signalled keys from a watch service then care

9
src/java.base/share/classes/java/nio/file/Watchable.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -97,9 +97,10 @@ public interface Watchable {
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* watchable.{@link #register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) register}(watcher, events, new WatchEvent.Modifier[0]);
* </pre>
* {@snippet lang=java :
* // @link substring="register" target=#register(WatchService,WatchEvent.Kind[],WatchEvent.Modifier[]) :
* register.watcher, events, new WatchEvent.Modifier[0]);
* }
*
* @param watcher
* the watch service to which this object is to be registered

8
src/java.base/share/classes/java/nio/file/attribute/AclFileAttributeView.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -69,7 +69,7 @@ import java.io.IOException;
*
* <p> <b>Usage Example:</b>
* Suppose we wish to add an entry to an existing ACL to grant "joe" access:
* <pre>
* {@snippet lang=java :
* // lookup "joe"
* UserPrincipal joe = file.getFileSystem().getUserPrincipalLookupService()
* .lookupPrincipalByName("joe");
@ -85,10 +85,10 @@ import java.io.IOException;
* .build();
*
* // read ACL, insert ACE, re-write ACL
* List&lt;AclEntry&gt; acl = view.getAcl();
* List<AclEntry> acl = view.getAcl();
* acl.add(0, entry); // insert before any DENY entries
* view.setAcl(acl);
* </pre>
* }
*
* <h2> Dynamic Access </h2>
* <p> Where dynamic access to file attributes is required, the attributes

12
src/java.base/share/classes/java/nio/file/attribute/BasicFileAttributeView.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -153,11 +153,11 @@ public interface BasicFileAttributeView
*
* <p> <b>Usage Example:</b>
* Suppose we want to change a file's last access time.
* <pre>
* Path path = ...
* FileTime time = ...
* Files.getFileAttributeView(path, BasicFileAttributeView.class).setTimes(null, time, null);
* </pre>
* {@snippet lang=java :
* Path path = ...
* FileTime time = ...
* Files.getFileAttributeView(path, BasicFileAttributeView.class).setTimes(null, time, null);
* }
*
* @param lastModifiedTime
* the new last modified time, or {@code null} to not change the

10
src/java.base/share/classes/java/nio/file/attribute/BasicFileAttributes.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -33,10 +33,10 @@ package java.nio.file.attribute;
* interface.
*
* <p> <b>Usage Example:</b>
* <pre>
* Path file = ...
* BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
* </pre>
* {@snippet lang=java :
* Path file = ...
* BasicFileAttributes attrs = Files.readAttributes(file, BasicFileAttributes.class);
* }
*
* @since 1.7
*

10
src/java.base/share/classes/java/nio/file/attribute/DosFileAttributes.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -30,10 +30,10 @@ package java.nio.file.attribute;
* legacy "DOS" attributes.
*
* <p> <b>Usage Example:</b>
* <pre>
* Path file = ...
* DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);
* </pre>
* {@snippet lang=java :
* Path file = ...
* DosFileAttributes attrs = Files.readAttributes(file, DosFileAttributes.class);
* }
*
* @since 1.7
*/

12
src/java.base/share/classes/java/nio/file/attribute/PosixFileAttributeView.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -59,14 +59,14 @@ import java.io.IOException;
*
* <p> <b>Usage Example:</b>
* Suppose we need to print out the owner and access permissions of a file:
* <pre>
* {@snippet lang=java :
* Path file = ...
* PosixFileAttributes attrs = Files.getFileAttributeView(file, PosixFileAttributeView.class)
* .readAttributes();
* System.out.format("%s %s%n",
* attrs.owner().getName(),
* PosixFilePermissions.toString(attrs.permissions()));
* </pre>
* }
*
* <h2> Dynamic Access </h2>
* <p> Where dynamic access to file attributes is required, the attributes
@ -118,12 +118,12 @@ import java.io.IOException;
* asFileAttribute} method to construct a {@code FileAttribute} when creating a
* file:
*
* <pre>
* {@snippet lang=java :
* Path path = ...
* Set&lt;PosixFilePermission&gt; perms =
* Set<PosixFilePermission> perms =
* EnumSet.of(OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ);
* Files.createFile(path, PosixFilePermissions.asFileAttribute(perms));
* </pre>
* }
*
* <p> When the access permissions are set at file creation time then the actual
* value of the permissions may differ from the value of the attribute object.

8
src/java.base/share/classes/java/nio/file/attribute/PosixFilePermissions.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -109,9 +109,9 @@ public final class PosixFilePermissions {
* Suppose we require the set of permissions that indicate the owner has read,
* write, and execute permissions, the group has read and execute permissions
* and others have none.
* <pre>
* Set&lt;PosixFilePermission&gt; perms = PosixFilePermissions.fromString("rwxr-x---");
* </pre>
* {@snippet lang=java :
* Set<PosixFilePermission> perms = PosixFilePermissions.fromString("rwxr-x---");
* }
*
* @param perms
* string representing a set of permissions

30
src/java.base/share/classes/java/nio/file/attribute/UserDefinedFileAttributeView.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2007, 2021, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2007, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -131,15 +131,15 @@ public interface UserDefinedFileAttributeView
* <p> <b>Usage Example:</b>
* Suppose we want to read a file's MIME type that is stored as a user-defined
* attribute with the name "{@code user.mimetype}".
* <pre>
* UserDefinedFileAttributeView view =
* Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* String name = "user.mimetype";
* ByteBuffer buf = ByteBuffer.allocate(view.size(name));
* view.read(name, buf);
* buf.flip();
* String value = Charset.defaultCharset().decode(buf).toString();
* </pre>
* {@snippet lang=java :
* UserDefinedFileAttributeView view =
* Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* String name = "user.mimetype";
* ByteBuffer buf = ByteBuffer.allocate(view.size(name));
* view.read(name, buf);
* buf.flip();
* String value = Charset.defaultCharset().decode(buf).toString();
* }
*
* @param name
* The attribute name
@ -188,11 +188,11 @@ public interface UserDefinedFileAttributeView
*
* <p> <b>Usage Example:</b>
* Suppose we want to write a file's MIME type as a user-defined attribute:
* <pre>
* UserDefinedFileAttributeView view =
* Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
* </pre>
* {@snippet lang=java :
* UserDefinedFileAttributeView view =
* Files.getFileAttributeView(path, UserDefinedFileAttributeView.class);
* view.write("user.mimetype", Charset.defaultCharset().encode("text/html"));
* }
*
* @param name
* The attribute name