archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +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

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