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

41
src/java.base/share/classes/java/nio/Buffer.java
View file

@ -181,15 +181,17 @@ import java.util.function.Function;
* specified to return the buffer upon which they are invoked. This allows
* method invocations to be chained; for example, the sequence of statements
*
* <blockquote><pre>
* b.flip();
* b.position(23);
* b.limit(42);</pre></blockquote>
* {@snippet lang=java :
* b.flip();
* b.position(23);
* b.limit(42);
* }
*
* can be replaced by the single, more compact statement
*
* <blockquote><pre>
* b.flip().position(23).limit(42);</pre></blockquote>
* {@snippet lang=java :
* b.flip().position(23).limit(42);
* }
*
*
* @author Mark Reinhold
@ -440,9 +442,10 @@ public abstract sealed class Buffer
* <p> Invoke this method before using a sequence of channel-read or
* <i>put</i> operations to fill this buffer. For example:
*
* <blockquote><pre>
* buf.clear(); // Prepare buffer for reading
* in.read(buf); // Read data</pre></blockquote>
* {@snippet lang=java :
* buf.clear(); // Prepare buffer for reading
* in.read(buf); // Read data
* }
*
* <p> This method does not actually erase the data in the buffer, but it
* is named as if it did because it will most often be used in situations
@ -466,11 +469,12 @@ public abstract sealed class Buffer
* this method to prepare for a sequence of channel-write or relative
* <i>get</i> operations. For example:
*
* <blockquote><pre>
* buf.put(magic); // Prepend header
* in.read(buf); // Read data into rest of buffer
* buf.flip(); // Flip buffer
* out.write(buf); // Write header + data to channel</pre></blockquote>
* {@snippet lang=java :
* buf.put(magic); // Prepend header
* in.read(buf); // Read data into rest of buffer
* buf.flip(); // Flip buffer
* out.write(buf); // Write header + data to channel
* }
*
* <p> This method is often used in conjunction with the {@link
* java.nio.ByteBuffer#compact compact} method when transferring data from
@ -493,10 +497,11 @@ public abstract sealed class Buffer
* operations, assuming that the limit has already been set
* appropriately. For example:
*
* <blockquote><pre>
* out.write(buf); // Write remaining data
* buf.rewind(); // Rewind buffer
* buf.get(array); // Copy data into array</pre></blockquote>
* {@snippet lang=java :
* out.write(buf); // Write remaining data
* buf.rewind(); // Rewind buffer
* buf.get(array); // Copy data into array
* }
*
* @return This buffer
*/

158
src/java.base/share/classes/java/nio/X-Buffer.java.template
View file

@ -149,12 +149,16 @@ import jdk.internal.util.ArraysSupport;
* <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point
* values, for example, this class defines:
*
* <blockquote><pre>
* float {@link #getFloat()}
* float {@link #getFloat(int) getFloat(int index)}
* ByteBuffer {@link #putFloat(float) putFloat(float f)}
* ByteBuffer {@link #putFloat(int,float) putFloat(int index, float f)}
* </pre></blockquote>
* {@snippet lang=java :
* // @link substring="getFloat()" target="#getFloat" :
* float getFloat()
* // @link substring="getFloat(int index)" target="#getFloat(int)" :
* float getFloat(int index)
* // @link substring="putFloat(float f)" target="#putFloat(float)" :
* ByteBuffer putFloat(float f)
* // @link substring="putFloat(int index, float f)" target="#putFloat(int,float)" :
* ByteBuffer putFloat(int index, float f)
* }
*
* <p> Corresponding methods are defined for the types {@code char,
* short, int, long}, and {@code double}. The index
@ -231,31 +235,35 @@ import jdk.internal.util.ArraysSupport;
*
* The sequence of statements
*
* <blockquote><pre>
* bb.putInt(0xCAFEBABE);
* bb.putShort(3);
* bb.putShort(45);</pre></blockquote>
* {@snippet lang=java :
* bb.putInt(0xCAFEBABE);
* bb.putShort(3);
* bb.putShort(45);
* }
*
* can, for example, be replaced by the single statement
*
* <blockquote><pre>
* bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote>
* {@snippet lang=java :
* bb.putInt(0xCAFEBABE).putShort(3).putShort(45);
* }
*
#end[byte]
#if[char]
*
* The sequence of statements
*
* <blockquote><pre>
* cb.put("text/");
* cb.put(subtype);
* cb.put("; charset=");
* cb.put(enc);</pre></blockquote>
* {@snippet lang=java :
* cb.put("text/");
* cb.put(subtype);
* cb.put("; charset=");
* cb.put(enc);
* }
*
* can, for example, be replaced by the single statement
*
* <blockquote><pre>
* cb.put("text/").put(subtype).put("; charset=").put(enc);</pre></blockquote>
* {@snippet lang=java :
* cb.put("text/").put(subtype).put("; charset=").put(enc);
* }
*
#end[char]
* <h2> Optional operations </h2>
@ -780,10 +788,10 @@ public abstract sealed class $Type$Buffer
* <code>src.get(dst,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
* the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = off; i < off + len; i++)
* dst[i] = src.get();
* }</pre>
* }
*
* except that it first checks that there are sufficient $type$s in
* this buffer and it is potentially much more efficient.
@ -830,8 +838,9 @@ public abstract sealed class $Type$Buffer
* destination array. An invocation of this method of the form
* {@code src.get(a)} behaves in exactly the same way as the invocation
*
* <pre>
* src.get(a, 0, a.length) </pre>
* {@snippet lang=java :
* src.get(a, 0, a.length)
* }
*
* @param dst
* The destination array
@ -860,10 +869,10 @@ public abstract sealed class $Type$Buffer
* checks the consistency of the supplied parameters and it is potentially
* much more efficient:
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst[i] = src.get(j);
* }</pre>
* }
*
* @param index
* The index in this buffer from which the first $type$ will be
@ -908,8 +917,9 @@ public abstract sealed class $Type$Buffer
* <code>src.get(index,&nbsp;dst)</code> behaves in exactly the same
* way as the invocation:
*
* <pre>
* src.get(index, dst, 0, dst.length) </pre>
* {@snippet lang=java :
* src.get(index, dst, 0, dst.length)
* }
*
* @param index
* The index in this buffer from which the first $type$ will be
@ -984,9 +994,10 @@ public abstract sealed class $Type$Buffer
* <p> In other words, an invocation of this method of the form
* {@code dst.put(src)} has exactly the same effect as the loop
*
* <pre>
* {@snippet lang=java :
* while (src.hasRemaining())
* dst.put(src.get()); </pre>
* dst.put(src.get());
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient. If this buffer and
@ -1046,10 +1057,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(index,&nbsp;src,&nbsp;offset,&nbsp;length)</code>
* has exactly the same effect as the loop
*
* <pre>{@code
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src.get(i));
* }</pre>
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src.get(i));
* }
*
* except that it first checks the consistency of the supplied parameters
* and it is potentially much more efficient. If this buffer and
@ -1158,10 +1169,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(src,&nbsp;off,&nbsp;len)</code> has exactly the same effect as
* the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = off; i < off + len; i++)
* dst.put(src[i]);
* }</pre>
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient.
@ -1212,8 +1223,9 @@ public abstract sealed class $Type$Buffer
* form {@code dst.put(a)} behaves in exactly the same way as the
* invocation
*
* <pre>
* dst.put(a, 0, a.length) </pre>
* {@snippet lang=java :
* dst.put(a, 0, a.length)
* }
*
* @param src
* The source array
@ -1243,10 +1255,10 @@ public abstract sealed class $Type$Buffer
* checks the consistency of the supplied parameters and it is potentially
* much more efficient:
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = offset, j = index; i < offset + length; i++, j++)
* dst.put(j, src[i]);
* }</pre>
* }
*
* @param index
* The index in this buffer at which the first $type$ will be
@ -1294,8 +1306,9 @@ public abstract sealed class $Type$Buffer
* method of the form <code>dst.put(index,&nbsp;src)</code>
* behaves in exactly the same way as the invocation:
*
* <pre>
* dst.put(index, src, 0, src.length); </pre>
* {@snippet lang=java :
* dst.put(index, src, 0, src.length);
* }
*
* @param index
* The index in this buffer at which the first $type$ will be
@ -1378,10 +1391,10 @@ public abstract sealed class $Type$Buffer
* <code>dst.put(src,&nbsp;start,&nbsp;end)</code> has exactly the same effect
* as the loop
*
* <pre>{@code
* {@snippet lang=java :
* for (int i = start; i < end; i++)
* dst.put(src.charAt(i));
* }</pre>
* }
*
* except that it first checks that there is sufficient space in this
* buffer and it is potentially much more efficient.
@ -1429,8 +1442,9 @@ public abstract sealed class $Type$Buffer
* into this buffer. An invocation of this method of the form
* {@code dst.put(s)} behaves in exactly the same way as the invocation
*
* <pre>
* dst.put(s, 0, s.length()) </pre>
* {@snippet lang=java :
* dst.put(s, 0, s.length())
* }
*
* @param src
* The source string
@ -1646,14 +1660,14 @@ public abstract sealed class $Type$Buffer
* write was incomplete. The following loop, for example, copies bytes
* from one channel to another via the buffer {@code buf}:
*
* <blockquote><pre>{@code
* buf.clear(); // Prepare buffer for use
* while (in.read(buf) >= 0 || buf.position != 0) {
* buf.flip();
* out.write(buf);
* buf.compact(); // In case of partial write
* }
* }</pre></blockquote>
* {@snippet lang=java :
* buf.clear(); // Prepare buffer for use
* while (in.read(buf) >= 0 || buf.position != 0) {
* buf.flip();
* out.write(buf);
* buf.compact(); // In case of partial write
* }
* }
*
#end[byte]
*
@ -1978,8 +1992,9 @@ public abstract sealed class $Type$Buffer
* <p> An invocation of this method of the form {@code dst.append(csq)}
* behaves in exactly the same way as the invocation
*
* <pre>
* dst.put(csq.toString()) </pre>
* {@snippet lang=java :
* dst.put(csq.toString())
* }
*
* <p> Depending on the specification of {@code toString} for the
* character sequence {@code csq}, the entire sequence may not be
@ -2019,8 +2034,9 @@ public abstract sealed class $Type$Buffer
* end)} when {@code csq} is not {@code null}, behaves in exactly the
* same way as the invocation
*
* <pre>
* dst.put(csq.subSequence(start, end).toString()) </pre>
* {@snippet lang=java :
* dst.put(csq.subSequence(start, end).toString())
* }
*
* @param csq
* The character sequence from which a subsequence will be
@ -2073,8 +2089,9 @@ public abstract sealed class $Type$Buffer
* <p> An invocation of this method of the form {@code dst.append($x$)}
* behaves in exactly the same way as the invocation
*
* <pre>
* dst.put($x$) </pre>
* {@snippet lang=java :
* dst.put($x$)
* }
*
* @param $x$
* The 16-bit $type$ to append
@ -2173,14 +2190,17 @@ public abstract sealed class $Type$Buffer
* aligned address. Specifically, the index should either be decremented by
* the return value if the latter is not greater than {@code index}, or be
* incremented by the unit size minus the return value. Therefore given
* <blockquote><pre>
* int value = alignmentOffset(index, unitSize)</pre></blockquote>
* {@snippet lang=java :
* int value = alignmentOffset(index, unitSize)
* }
* then the identities
* <blockquote><pre>
* alignmentOffset(index - value, unitSize) == 0, value &le; index</pre></blockquote>
* {@snippet lang=java :
* alignmentOffset(index - value, unitSize) == 0, value <= index
* }
* and
* <blockquote><pre>
* alignmentOffset(index + (unitSize - value), unitSize) == 0</pre></blockquote>
* {@snippet lang=java :
* alignmentOffset(index + (unitSize - value), unitSize) == 0
* }
* must hold.
*
* @apiNote
@ -2239,10 +2259,10 @@ public abstract sealed class $Type$Buffer
* and limit will be zero. If rounding is within bounds the following
* expressions will be true for a new buffer {@code nb} and unit size
* {@code unitSize}:
* <pre>{@code
* nb.alignmentOffset(0, unitSize) == 0
* nb.alignmentOffset(nb.limit(), unitSize) == 0
* }</pre>
* {@snippet lang=java :
* nb.alignmentOffset(0, unitSize) == 0
* nb.alignmentOffset(nb.limit(), unitSize) == 0
* }
*
* <p> Changes to this buffer's content will be visible in the new
* buffer, and vice versa; the two buffers' position, limit, and mark

30
src/java.base/share/classes/java/nio/channels/AsynchronousFileChannel.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
@ -268,10 +268,10 @@ public abstract class AsynchronousFileChannel
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* ch.{@link #open(Path,Set,ExecutorService,FileAttribute[])
* open}(file, opts, null, new FileAttribute&lt;?&gt;[0]);
* </pre>
* {@snippet lang=java :
* // @link substring="open" target="#open(Path,Set,ExecutorService,FileAttribute[])" :
* ch.open(file, opts, null, new FileAttribute<?>[0]);
* }
* where {@code opts} is a {@code Set} containing the options specified to
* this method.
*
@ -499,9 +499,10 @@ public abstract class AsynchronousFileChannel
*
* <p> An invocation of this method of the form {@code ch.lock(att,handler)}
* behaves in exactly the same way as the invocation
* <pre>
* ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)
* </pre>
* {@snippet lang=java :
* // @link substring="lock" target="#lock(long,long,boolean,Object,CompletionHandler)" :
* ch.lock(0L, Long.MAX_VALUE, false, att, handler)
* }
*
* @param <A>
* The type of the attachment
@ -572,9 +573,10 @@ public abstract class AsynchronousFileChannel
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* ch.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false)
* </pre>
* {@snippet lang=java :
* // @link substring="lock" target="#lock(long,long,boolean)" :
* ch.lock(0L, Long.MAX_VALUE, false)
* }
*
* @return a {@code Future} object representing the pending result
*
@ -648,8 +650,10 @@ public abstract class AsynchronousFileChannel
* <p> An invocation of this method of the form {@code ch.tryLock()}
* behaves in exactly the same way as the invocation
*
* <pre>
* ch.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
* {@snippet lang=java :
* // @link substring="tryLock" target="#tryLock(long,long,boolean)" :
* ch.tryLock(0L, Long.MAX_VALUE, false)
* }
*
* @return A lock object representing the newly-acquired lock,
* or {@code null} if the lock could not be acquired

20
src/java.base/share/classes/java/nio/channels/AsynchronousServerSocketChannel.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
@ -75,11 +75,11 @@ import java.io.IOException;
* Additional (implementation specific) options may also be supported.
*
* <p> <b>Usage Example:</b>
* <pre>
* {@snippet lang=java :
* final AsynchronousServerSocketChannel listener =
* AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));
*
* listener.accept(null, new CompletionHandler&lt;AsynchronousSocketChannel,Void&gt;() {
* listener.accept(null, new CompletionHandler<AsynchronousSocketChannel,Void>() {
* public void completed(AsynchronousSocketChannel ch, Void att) {
* // accept the next connection
* listener.accept(null, this);
@ -91,7 +91,7 @@ import java.io.IOException;
* ...
* }
* });
* </pre>
* }
*
* @since 1.7
*/
@ -156,9 +156,9 @@ public abstract class AsynchronousServerSocketChannel
* <p> This method returns an asynchronous server socket channel that is
* bound to the <em>default group</em>. This method is equivalent to evaluating
* the expression:
* <blockquote><pre>
* open((AsynchronousChannelGroup)null);
* </pre></blockquote>
* {@snippet lang=java :
* open((AsynchronousChannelGroup)null);
* }
*
* @return A new asynchronous server socket channel
*
@ -176,9 +176,9 @@ public abstract class AsynchronousServerSocketChannel
* listen for connections.
*
* <p> An invocation of this method is equivalent to the following:
* <blockquote><pre>
* bind(local, 0);
* </pre></blockquote>
* {@snippet lang=java :
* bind(local, 0);
* }
*
* @param local
* The local address to bind the socket, or {@code null} to bind

26
src/java.base/share/classes/java/nio/channels/AsynchronousSocketChannel.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
@ -180,9 +180,9 @@ public abstract class AsynchronousSocketChannel
* <p> This method returns an asynchronous socket channel that is bound to
* the <em>default group</em>.This method is equivalent to evaluating the
* expression:
* <blockquote><pre>
* open((AsynchronousChannelGroup)null);
* </pre></blockquote>
* {@snippet lang=java :
* open((AsynchronousChannelGroup)null);
* }
*
* @return A new asynchronous socket channel
*
@ -449,10 +449,11 @@ public abstract class AsynchronousSocketChannel
* where <i>r</i> is the total number of bytes remaining in the specified
* subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* dsts[offset].remaining()
* + dsts[offset+1].remaining()
* + ... + dsts[offset+length-1].remaining()</pre></blockquote>
* {@snippet lang=java :
* dsts[offset].remaining()
* + dsts[offset+1].remaining()
* + ... + dsts[offset+length-1].remaining()
* }
*
* at the moment that the read is attempted.
*
@ -603,10 +604,11 @@ public abstract class AsynchronousSocketChannel
* where <i>r</i> is the total number of bytes remaining in the specified
* subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* srcs[offset].remaining()
* + srcs[offset+1].remaining()
* + ... + srcs[offset+length-1].remaining()</pre></blockquote>
* {@snippet lang=java :
* srcs[offset].remaining()
* + srcs[offset+1].remaining()
* + ... + srcs[offset+length-1].remaining()
* }
*
* at the moment that the write is attempted.
*

32
src/java.base/share/classes/java/nio/channels/Channels.java
View file

@ -448,15 +448,15 @@ public final class Channels {
*
* <p> An invocation of this method of the form
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newReader(ch, csname)
* } </pre>
* }
*
* behaves in exactly the same way as the expression
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newReader(ch, Charset.forName(csName))
* } </pre>
* }
*
* @param ch
* The channel from which bytes will be read
@ -483,15 +483,15 @@ public final class Channels {
*
* <p> An invocation of this method of the form
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newReader(ch, charset)
* } </pre>
* }
*
* behaves in exactly the same way as the expression
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newReader(ch, charset.newDecoder(), -1)
* } </pre>
* }
*
* <p> The reader's default action for malformed-input and unmappable-character
* errors is to {@linkplain java.nio.charset.CodingErrorAction#REPORT report}
@ -548,15 +548,15 @@ public final class Channels {
*
* <p> An invocation of this method of the form
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newWriter(ch, csname)
* } </pre>
* }
*
* behaves in exactly the same way as the expression
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newWriter(ch, Charset.forName(csName))
* } </pre>
* }
*
* @param ch
* The channel to which bytes will be written
@ -583,15 +583,15 @@ public final class Channels {
*
* <p> An invocation of this method of the form
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newWriter(ch, charset)
* } </pre>
* }
*
* behaves in exactly the same way as the expression
*
* <pre> {@code
* {@snippet lang=java :
* Channels.newWriter(ch, charset.newEncoder(), -1)
* } </pre>
* }
*
* <p> The writer's default action for malformed-input and unmappable-character
* errors is to {@linkplain java.nio.charset.CodingErrorAction#REPORT report}

19
src/java.base/share/classes/java/nio/channels/FileChannel.java
View file

@ -317,9 +317,10 @@ public abstract class FileChannel
*
* <p> An invocation of this method behaves in exactly the same way as the
* invocation
* <pre>
* fc.{@link #open(Path,Set,FileAttribute[]) open}(file, opts, new FileAttribute&lt;?&gt;[0]);
* </pre>
* {@snippet lang=java :
* // @link substring="open" target="#open(Path,Set,FileAttribute[])" :
* fc.open(file, opts, new FileAttribute<?>[0]);
* }
* where {@code opts} is a set of the options specified in the {@code
* options} array.
*
@ -1201,8 +1202,10 @@ public abstract class FileChannel
* <p> An invocation of this method of the form {@code fc.lock()} behaves
* in exactly the same way as the invocation
*
* <pre>
* fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre>
* {@snippet lang=java :
* // @link substring="lock" target="#lock(long,long,boolean)" :
* fc.lock(0L, Long.MAX_VALUE, false)
* }
*
* @return A lock object representing the newly-acquired lock
*
@ -1325,8 +1328,10 @@ public abstract class FileChannel
* <p> An invocation of this method of the form {@code fc.tryLock()}
* behaves in exactly the same way as the invocation
*
* <pre>
* fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
* {@snippet lang=java :
* // @link substring="tryLock" target="#tryLock(long,long,boolean)" :
* fc.tryLock(0L, Long.MAX_VALUE, false)
* }
*
* @return A lock object representing the newly-acquired lock,
* or {@code null} if the lock could not be acquired

16
src/java.base/share/classes/java/nio/channels/GatheringByteChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -58,10 +58,11 @@ public interface GatheringByteChannel
* where <i>r</i> is the total number of bytes remaining in the specified
* subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* srcs[offset].remaining()
* + srcs[offset+1].remaining()
* + ... + srcs[offset+length-1].remaining()</pre></blockquote>
* {@snippet lang=java :
* srcs[offset].remaining()
* + srcs[offset+1].remaining()
* + ... + srcs[offset+length-1].remaining()
* }
*
* at the moment that this method is invoked.
*
@ -134,8 +135,9 @@ public interface GatheringByteChannel
* <p> An invocation of this method of the form {@code c.write(srcs)}
* behaves in exactly the same manner as the invocation
*
* <blockquote><pre>
* c.write(srcs, 0, srcs.length);</pre></blockquote>
* {@snippet lang=java :
* c.write(srcs, 0, srcs.length);
* }
*
* @param srcs
* The buffers from which bytes are to be retrieved

6
src/java.base/share/classes/java/nio/channels/MulticastChannel.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
@ -102,7 +102,7 @@ import java.net.StandardSocketOptions; // javadoc
* </ol>
*
* <p> <b>Usage Example:</b>
* <pre>
* {@snippet lang=java :
* // join multicast group on this interface, and also use this
* // interface for outgoing multicast datagrams
* NetworkInterface ni = NetworkInterface.getByName("hme0");
@ -115,7 +115,7 @@ import java.net.StandardSocketOptions; // javadoc
* InetAddress group = InetAddress.getByName("225.4.5.6");
*
* MembershipKey key = dc.join(group, ni);
* </pre>
* }
*
* @spec https://www.rfc-editor.org/info/rfc2236
* RFC 2236: Internet Group Management Protocol, Version 2

16
src/java.base/share/classes/java/nio/channels/ScatteringByteChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -58,10 +58,11 @@ public interface ScatteringByteChannel
* from this channel, where <i>r</i> is the total number of bytes remaining
* the specified subsequence of the given buffer array, that is,
*
* <blockquote><pre>
* dsts[offset].remaining()
* + dsts[offset+1].remaining()
* + ... + dsts[offset+length-1].remaining()</pre></blockquote>
* {@snippet lang=java :
* dsts[offset].remaining()
* + dsts[offset+1].remaining()
* + ... + dsts[offset+length-1].remaining()
* }
*
* at the moment that this method is invoked.
*
@ -132,8 +133,9 @@ public interface ScatteringByteChannel
* <p> An invocation of this method of the form {@code c.read(dsts)}
* behaves in exactly the same manner as the invocation
*
* <blockquote><pre>
* c.read(dsts, 0, dsts.length);</pre></blockquote>
* {@snippet lang=java :
* c.read(dsts, 0, dsts.length);
* }
*
* @param dsts
* The buffers into which bytes are to be transferred

26
src/java.base/share/classes/java/nio/channels/SelectionKey.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -338,9 +338,9 @@ public abstract class SelectionKey {
* <p> An invocation of this method of the form {@code k.isReadable()}
* behaves in exactly the same way as the expression
*
* <blockquote><pre>{@code
* k.readyOps() & OP_READ != 0
* }</pre></blockquote>
* {@snippet lang=java :
* k.readyOps() & OP_READ != 0
* }
*
* <p> If this key's channel does not support read operations then this
* method always returns {@code false}. </p>
@ -361,9 +361,9 @@ public abstract class SelectionKey {
* <p> An invocation of this method of the form {@code k.isWritable()}
* behaves in exactly the same way as the expression
*
* <blockquote><pre>{@code
* k.readyOps() & OP_WRITE != 0
* }</pre></blockquote>
* {@snippet lang=java :
* k.readyOps() & OP_WRITE != 0
* }
*
* <p> If this key's channel does not support write operations then this
* method always returns {@code false}. </p>
@ -385,9 +385,9 @@ public abstract class SelectionKey {
* <p> An invocation of this method of the form {@code k.isConnectable()}
* behaves in exactly the same way as the expression
*
* <blockquote><pre>{@code
* k.readyOps() & OP_CONNECT != 0
* }</pre></blockquote>
* {@snippet lang=java :
* k.readyOps() & OP_CONNECT != 0
* }
*
* <p> If this key's channel does not support socket-connect operations
* then this method always returns {@code false}. </p>
@ -409,9 +409,9 @@ public abstract class SelectionKey {
* <p> An invocation of this method of the form {@code k.isAcceptable()}
* behaves in exactly the same way as the expression
*
* <blockquote><pre>{@code
* k.readyOps() & OP_ACCEPT != 0
* }</pre></blockquote>
* {@snippet lang=java :
* k.readyOps() & OP_ACCEPT != 0
* }
*
* <p> If this key's channel does not support socket-accept operations then
* this method always returns {@code false}. </p>

8
src/java.base/share/classes/java/nio/channels/ServerSocketChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -198,9 +198,9 @@ public abstract class ServerSocketChannel
* to listen for connections.
*
* <p> An invocation of this method is equivalent to the following:
* <blockquote><pre>
* bind(local, 0);
* </pre></blockquote>
* {@snippet lang=java :
* bind(local, 0);
* }
*
* @param local
* The local address to bind the socket, or {@code null} to bind

21
src/java.base/share/classes/java/nio/channels/spi/AbstractInterruptibleChannel.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -46,15 +46,16 @@ import sun.nio.ch.Interruptible;
* invoked, these methods should be used within a
* {@code try}&nbsp;...&nbsp;{@code finally} block:
*
* <blockquote><pre id="be">
* boolean completed = false;
* try {
* begin();
* completed = ...; // Perform blocking I/O operation
* return ...; // Return result
* } finally {
* end(completed);
* }</pre></blockquote>
* {@snippet lang=java id="be" :
* boolean completed = false;
* try {
* begin();
* completed = ...; // Perform blocking I/O operation
* return ...; // Return result
* } finally {
* end(completed);
* }
* }
*
* <p> The {@code completed} argument to the {@link #end end} method tells
* whether or not the I/O operation actually completed, that is, whether it had

19
src/java.base/share/classes/java/nio/channels/spi/AbstractSelector.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2000, 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
@ -47,14 +47,15 @@ import sun.nio.ch.SelectorImpl;
* invoked, these methods should be used within a
* {@code try}&nbsp;...&nbsp;{@code finally} block:
*
* <blockquote><pre id="be">
* try {
* begin();
* // Perform blocking I/O operation here
* ...
* } finally {
* end();
* }</pre></blockquote>
* {@snippet lang=java id="be" :
* try {
* begin();
* // Perform blocking I/O operation here
* ...
* } finally {
* end();
* }
* }
*
* <p> This class also defines methods for maintaining a selector's
* cancelled-key set and for removing a key from its channel's key set, and

15
src/java.base/share/classes/java/nio/charset/Charset.java
View file

@ -840,11 +840,12 @@ public abstract class Charset
* <p> An invocation of this method upon a charset {@code cs} returns the
* same result as the expression
*
* <pre>
* {@snippet lang=java :
* cs.newDecoder()
* .onMalformedInput(CodingErrorAction.REPLACE)
* .onUnmappableCharacter(CodingErrorAction.REPLACE)
* .decode(bb); </pre>
* .decode(bb);
* }
*
* except that it is potentially more efficient because it can cache
* decoders between successive invocations.
@ -876,11 +877,12 @@ public abstract class Charset
* <p> An invocation of this method upon a charset {@code cs} returns the
* same result as the expression
*
* <pre>
* {@snippet lang=java :
* cs.newEncoder()
* .onMalformedInput(CodingErrorAction.REPLACE)
* .onUnmappableCharacter(CodingErrorAction.REPLACE)
* .encode(bb); </pre>
* .encode(bb);
* }
*
* except that it is potentially more efficient because it can cache
* encoders between successive invocations.
@ -911,8 +913,9 @@ public abstract class Charset
* <p> An invocation of this method upon a charset {@code cs} returns the
* same result as the expression
*
* <pre>
* cs.encode(CharBuffer.wrap(s)); </pre>
* {@snippet lang=java :
* cs.encode(CharBuffer.wrap(s));
* }
*
* @param str The string to be encoded
*

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