History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/nio/channels (86 of 18352 files). Show all

Unified · Split

86 files
  1. java/pkg/java/nio/channels/AsynchronousByteChannel.class +0 −0
  2. java/pkg/java/nio/channels/AsynchronousByteChannel.java +209 −0
  3. java/pkg/java/nio/channels/AsynchronousChannel.class +0 −0
  4. java/pkg/java/nio/channels/AsynchronousChannel.java +117 −0
  5. java/pkg/java/nio/channels/AsynchronousChannelGroup.class +0 −0
  6. java/pkg/java/nio/channels/AsynchronousChannelGroup.java +344 −0
  7. java/pkg/java/nio/channels/AsynchronousFileChannel.class +0 −0
  8. java/pkg/java/nio/channels/AsynchronousFileChannel.java +770 −0
  9. java/pkg/java/nio/channels/AsynchronousServerSocketChannel.class +0 −0
  10. java/pkg/java/nio/channels/AsynchronousServerSocketChannel.java +300 −0
  11. java/pkg/java/nio/channels/AsynchronousSocketChannel.class +0 −0
  12. java/pkg/java/nio/channels/AsynchronousSocketChannel.java +648 −0
  13. java/pkg/java/nio/channels/ByteChannel.class +0 −0
  14. java/pkg/java/nio/channels/ByteChannel.java +45 −0
  15. java/pkg/java/nio/channels/Channel.class +0 −0
  16. java/pkg/java/nio/channels/Channel.java +84 −0
  17. java/pkg/java/nio/channels/Channels$1.class +0 −0
  18. java/pkg/java/nio/channels/Channels$2.class +0 −0
  19. java/pkg/java/nio/channels/Channels$3.class +0 −0
  20. java/pkg/java/nio/channels/Channels$ReadableByteChannelImpl.class +0 −0
  21. java/pkg/java/nio/channels/Channels$WritableByteChannelImpl.class +0 −0
  22. java/pkg/java/nio/channels/Channels.class +0 −0
  23. java/pkg/java/nio/channels/Channels.java +615 −0
  24. java/pkg/java/nio/channels/CompletionHandler.class +0 −0
  25. java/pkg/java/nio/channels/CompletionHandler.java +66 −0
  26. java/pkg/java/nio/channels/DatagramChannel.class +0 −0
  27. java/pkg/java/nio/channels/DatagramChannel.java +568 −0
  28. java/pkg/java/nio/channels/FileChannel$MapMode.class +0 −0
  29. java/pkg/java/nio/channels/FileChannel.class +0 −0
  30. java/pkg/java/nio/channels/FileChannel.java +1157 −0
  31. java/pkg/java/nio/channels/FileLock.class +0 −0
  32. java/pkg/java/nio/channels/FileLock.java +326 −0
  33. java/pkg/java/nio/channels/GatheringByteChannel.class +0 −0
  34. java/pkg/java/nio/channels/GatheringByteChannel.java +166 −0
  35. java/pkg/java/nio/channels/InterruptibleChannel.class +0 −0
  36. java/pkg/java/nio/channels/InterruptibleChannel.java +82 −0
  37. java/pkg/java/nio/channels/MembershipKey.class +0 −0
  38. java/pkg/java/nio/channels/MembershipKey.java +177 −0
  39. java/pkg/java/nio/channels/MulticastChannel.class +0 −0
  40. java/pkg/java/nio/channels/MulticastChannel.java +230 −0
  41. java/pkg/java/nio/channels/NetworkChannel.class +0 −0
  42. java/pkg/java/nio/channels/NetworkChannel.java +160 −0
  43. java/pkg/java/nio/channels/Pipe$SinkChannel.class +0 −0
  44. java/pkg/java/nio/channels/Pipe$SourceChannel.class +0 −0
  45. java/pkg/java/nio/channels/Pipe.class +0 −0
  46. java/pkg/java/nio/channels/Pipe.java +153 −0
  47. java/pkg/java/nio/channels/ReadableByteChannel.class +0 −0
  48. java/pkg/java/nio/channels/ReadableByteChannel.java +108 −0
  49. java/pkg/java/nio/channels/ScatteringByteChannel.class +0 −0
  50. java/pkg/java/nio/channels/ScatteringByteChannel.java +162 −0
  51. java/pkg/java/nio/channels/SeekableByteChannel.class +0 −0
  52. java/pkg/java/nio/channels/SeekableByteChannel.java +168 −0
  53. java/pkg/java/nio/channels/SelectableChannel.class +0 −0
  54. java/pkg/java/nio/channels/SelectableChannel.java +342 −0
  55. java/pkg/java/nio/channels/SelectionKey.class +0 −0
  56. java/pkg/java/nio/channels/SelectionKey.java +401 −0
  57. java/pkg/java/nio/channels/Selector.class +0 −0
  58. java/pkg/java/nio/channels/Selector.java +396 −0
  59. java/pkg/java/nio/channels/ServerSocketChannel.class +0 −0
  60. java/pkg/java/nio/channels/ServerSocketChannel.java +268 −0
  61. java/pkg/java/nio/channels/SocketChannel.class +0 −0
  62. java/pkg/java/nio/channels/SocketChannel.java +496 −0
  63. java/pkg/java/nio/channels/WritableByteChannel.class +0 −0
  64. java/pkg/java/nio/channels/WritableByteChannel.java +105 −0
  65. java/pkg/java/nio/channels/exceptions +194 −0
  66. java/pkg/java/nio/channels/mkfile +40 −0
  67. java/pkg/java/nio/channels/package-info.java +290 −0
  68. java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel$1.class +0 −0
  69. java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel.class +0 −0
  70. java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel.java +214 −0
  71. java/pkg/java/nio/channels/spi/AbstractSelectableChannel.class +0 −0
  72. java/pkg/java/nio/channels/spi/AbstractSelectableChannel.java +305 −0
  73. java/pkg/java/nio/channels/spi/AbstractSelectionKey.class +0 −0
  74. java/pkg/java/nio/channels/spi/AbstractSelectionKey.java +77 −0
  75. java/pkg/java/nio/channels/spi/AbstractSelector$1.class +0 −0
  76. java/pkg/java/nio/channels/spi/AbstractSelector.class +0 −0
  77. java/pkg/java/nio/channels/spi/AbstractSelector.java +231 −0
  78. java/pkg/java/nio/channels/spi/AsynchronousChannelProvider$ProviderHolder$1.class +0 −0
  79. java/pkg/java/nio/channels/spi/AsynchronousChannelProvider$ProviderHolder.class +0 −0
  80. java/pkg/java/nio/channels/spi/AsynchronousChannelProvider.class +0 −0
  81. java/pkg/java/nio/channels/spi/AsynchronousChannelProvider.java +241 −0
  82. java/pkg/java/nio/channels/spi/SelectorProvider$1.class +0 −0
  83. java/pkg/java/nio/channels/spi/SelectorProvider.class +0 −0
  84. java/pkg/java/nio/channels/spi/SelectorProvider.java +302 −0
  85. java/pkg/java/nio/channels/spi/mkfile +13 −0
  86. java/pkg/java/nio/channels/spi/package.html +45 −0
java/pkg/java/nio/channels/AsynchronousByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousByteChannel.java+209−0
@@ -0,0 +1,209 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.ByteBuffer;
29+import java.util.concurrent.Future;
30+
31+/**
32+ * An asynchronous channel that can read and write bytes.
33+ *
34+ * <p> Some channels may not allow more than one read or write to be outstanding
35+ * at any given time. If a thread invokes a read method before a previous read
36+ * operation has completed then a {@link ReadPendingException} will be thrown.
37+ * Similarly, if a write method is invoked before a previous write has completed
38+ * then {@link WritePendingException} is thrown. Whether or not other kinds of
39+ * I/O operations may proceed concurrently with a read operation depends upon
40+ * the type of the channel.
41+ *
42+ * <p> Note that {@link java.nio.ByteBuffer ByteBuffers} are not safe for use by
43+ * multiple concurrent threads. When a read or write operation is initiated then
44+ * care must be taken to ensure that the buffer is not accessed until the
45+ * operation completes.
46+ *
47+ * @see Channels#newInputStream(AsynchronousByteChannel)
48+ * @see Channels#newOutputStream(AsynchronousByteChannel)
49+ *
50+ * @since 1.7
51+ */
52+
53+public interface AsynchronousByteChannel
54+ extends AsynchronousChannel
55+{
56+ /**
57+ * Reads a sequence of bytes from this channel into the given buffer.
58+ *
59+ * <p> This method initiates an asynchronous read operation to read a
60+ * sequence of bytes from this channel into the given buffer. The {@code
61+ * handler} parameter is a completion handler that is invoked when the read
62+ * operation completes (or fails). The result passed to the completion
63+ * handler is the number of bytes read or {@code -1} if no bytes could be
64+ * read because the channel has reached end-of-stream.
65+ *
66+ * <p> The read operation may read up to <i>r</i> bytes from the channel,
67+ * where <i>r</i> is the number of bytes remaining in the buffer, that is,
68+ * {@code dst.remaining()} at the time that the read is attempted. Where
69+ * <i>r</i> is 0, the read operation completes immediately with a result of
70+ * {@code 0} without initiating an I/O operation.
71+ *
72+ * <p> Suppose that a byte sequence of length <i>n</i> is read, where
73+ * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
74+ * This byte sequence will be transferred into the buffer so that the first
75+ * byte in the sequence is at index <i>p</i> and the last byte is at index
76+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>,
77+ * where <i>p</i> is the buffer's position at the moment the read is
78+ * performed. Upon completion the buffer's position will be equal to
79+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
80+ *
81+ * <p> Buffers are not safe for use by multiple concurrent threads so care
82+ * should be taken to not access the buffer until the operation has
83+ * completed.
84+ *
85+ * <p> This method may be invoked at any time. Some channel types may not
86+ * allow more than one read to be outstanding at any given time. If a thread
87+ * initiates a read operation before a previous read operation has
88+ * completed then a {@link ReadPendingException} will be thrown.
89+ *
90+ * @param dst
91+ * The buffer into which bytes are to be transferred
92+ * @param attachment
93+ * The object to attach to the I/O operation; can be {@code null}
94+ * @param handler
95+ * The completion handler
96+ *
97+ * @throws IllegalArgumentException
98+ * If the buffer is read-only
99+ * @throws ReadPendingException
100+ * If the channel does not allow more than one read to be outstanding
101+ * and a previous read has not completed
102+ * @throws ShutdownChannelGroupException
103+ * If the channel is associated with a {@link AsynchronousChannelGroup
104+ * group} that has terminated
105+ */
106+ <A> void read(ByteBuffer dst,
107+ A attachment,
108+ CompletionHandler<Integer,? super A> handler);
109+
110+ /**
111+ * Reads a sequence of bytes from this channel into the given buffer.
112+ *
113+ * <p> This method initiates an asynchronous read operation to read a
114+ * sequence of bytes from this channel into the given buffer. The method
115+ * behaves in exactly the same manner as the {@link
116+ * #read(ByteBuffer,Object,CompletionHandler)
117+ * read(ByteBuffer,Object,CompletionHandler)} method except that instead
118+ * of specifying a completion handler, this method returns a {@code Future}
119+ * representing the pending result. The {@code Future}'s {@link Future#get()
120+ * get} method returns the number of bytes read or {@code -1} if no bytes
121+ * could be read because the channel has reached end-of-stream.
122+ *
123+ * @param dst
124+ * The buffer into which bytes are to be transferred
125+ *
126+ * @return A Future representing the result of the operation
127+ *
128+ * @throws IllegalArgumentException
129+ * If the buffer is read-only
130+ * @throws ReadPendingException
131+ * If the channel does not allow more than one read to be outstanding
132+ * and a previous read has not completed
133+ */
134+ Future<Integer> read(ByteBuffer dst);
135+
136+ /**
137+ * Writes a sequence of bytes to this channel from the given buffer.
138+ *
139+ * <p> This method initiates an asynchronous write operation to write a
140+ * sequence of bytes to this channel from the given buffer. The {@code
141+ * handler} parameter is a completion handler that is invoked when the write
142+ * operation completes (or fails). The result passed to the completion
143+ * handler is the number of bytes written.
144+ *
145+ * <p> The write operation may write up to <i>r</i> bytes to the channel,
146+ * where <i>r</i> is the number of bytes remaining in the buffer, that is,
147+ * {@code src.remaining()} at the time that the write is attempted. Where
148+ * <i>r</i> is 0, the write operation completes immediately with a result of
149+ * {@code 0} without initiating an I/O operation.
150+ *
151+ * <p> Suppose that a byte sequence of length <i>n</i> is written, where
152+ * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
153+ * This byte sequence will be transferred from the buffer starting at index
154+ * <i>p</i>, where <i>p</i> is the buffer's position at the moment the
155+ * write is performed; the index of the last byte written will be
156+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>.
157+ * Upon completion the buffer's position will be equal to
158+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
159+ *
160+ * <p> Buffers are not safe for use by multiple concurrent threads so care
161+ * should be taken to not access the buffer until the operation has
162+ * completed.
163+ *
164+ * <p> This method may be invoked at any time. Some channel types may not
165+ * allow more than one write to be outstanding at any given time. If a thread
166+ * initiates a write operation before a previous write operation has
167+ * completed then a {@link WritePendingException} will be thrown.
168+ *
169+ * @param src
170+ * The buffer from which bytes are to be retrieved
171+ * @param attachment
172+ * The object to attach to the I/O operation; can be {@code null}
173+ * @param handler
174+ * The completion handler object
175+ *
176+ * @throws WritePendingException
177+ * If the channel does not allow more than one write to be outstanding
178+ * and a previous write has not completed
179+ * @throws ShutdownChannelGroupException
180+ * If the channel is associated with a {@link AsynchronousChannelGroup
181+ * group} that has terminated
182+ */
183+ <A> void write(ByteBuffer src,
184+ A attachment,
185+ CompletionHandler<Integer,? super A> handler);
186+
187+ /**
188+ * Writes a sequence of bytes to this channel from the given buffer.
189+ *
190+ * <p> This method initiates an asynchronous write operation to write a
191+ * sequence of bytes to this channel from the given buffer. The method
192+ * behaves in exactly the same manner as the {@link
193+ * #write(ByteBuffer,Object,CompletionHandler)
194+ * write(ByteBuffer,Object,CompletionHandler)} method except that instead
195+ * of specifying a completion handler, this method returns a {@code Future}
196+ * representing the pending result. The {@code Future}'s {@link Future#get()
197+ * get} method returns the number of bytes written.
198+ *
199+ * @param src
200+ * The buffer from which bytes are to be retrieved
201+ *
202+ * @return A Future representing the result of the operation
203+ *
204+ * @throws WritePendingException
205+ * If the channel does not allow more than one write to be outstanding
206+ * and a previous write has not completed
207+ */
208+ Future<Integer> write(ByteBuffer src);
209+}
java/pkg/java/nio/channels/AsynchronousChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousChannel.java+117−0
@@ -0,0 +1,117 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.util.concurrent.Future; // javadoc
30+
31+/**
32+ * A channel that supports asynchronous I/O operations. Asynchronous I/O
33+ * operations will usually take one of two forms:
34+ *
35+ * <ol>
36+ * <li><pre>{@link Future}&lt;V&gt; <em>operation</em>(<em>...</em>)</pre></li>
37+ * <li><pre>void <em>operation</em>(<em>...</em> A attachment, {@link
38+ * CompletionHandler}&lt;V,? super A&gt; handler)</pre></li>
39+ * </ol>
40+ *
41+ * where <i>operation</i> is the name of the I/O operation (read or write for
42+ * example), <i>V</i> is the result type of the I/O operation, and <i>A</i> is
43+ * the type of an object attached to the I/O operation to provide context when
44+ * consuming the result. The attachment is important for cases where a
45+ * <em>state-less</em> {@code CompletionHandler} is used to consume the result
46+ * of many I/O operations.
47+ *
48+ * <p> In the first form, the methods defined by the {@link Future Future}
49+ * interface may be used to check if the operation has completed, wait for its
50+ * completion, and to retrieve the result. In the second form, a {@link
51+ * CompletionHandler} is invoked to consume the result of the I/O operation when
52+ * it completes or fails.
53+ *
54+ * <p> A channel that implements this interface is <em>asynchronously
55+ * closeable</em>: If an I/O operation is outstanding on the channel and the
56+ * channel's {@link #close close} method is invoked, then the I/O operation
57+ * fails with the exception {@link AsynchronousCloseException}.
58+ *
59+ * <p> Asynchronous channels are safe for use by multiple concurrent threads.
60+ * Some channel implementations may support concurrent reading and writing, but
61+ * may not allow more than one read and one write operation to be outstanding at
62+ * any given time.
63+ *
64+ * <h4>Cancellation</h4>
65+ *
66+ * <p> The {@code Future} interface defines the {@link Future#cancel cancel}
67+ * method to cancel execution. This causes all threads waiting on the result of
68+ * the I/O operation to throw {@link java.util.concurrent.CancellationException}.
69+ * Whether the underlying I/O operation can be cancelled is highly implementation
70+ * specific and therefore not specified. Where cancellation leaves the channel,
71+ * or the entity to which it is connected, in an inconsistent state, then the
72+ * channel is put into an implementation specific <em>error state</em> that
73+ * prevents further attempts to initiate I/O operations that are <i>similar</i>
74+ * to the operation that was cancelled. For example, if a read operation is
75+ * cancelled but the implementation cannot guarantee that bytes have not been
76+ * read from the channel then it puts the channel into an error state; further
77+ * attempts to initiate a {@code read} operation cause an unspecified runtime
78+ * exception to be thrown. Similarly, if a write operation is cancelled but the
79+ * implementation cannot guarantee that bytes have not been written to the
80+ * channel then subsequent attempts to initiate a {@code write} will fail with
81+ * an unspecified runtime exception.
82+ *
83+ * <p> Where the {@link Future#cancel cancel} method is invoked with the {@code
84+ * mayInterruptIfRunning} parameter set to {@code true} then the I/O operation
85+ * may be interrupted by closing the channel. In that case all threads waiting
86+ * on the result of the I/O operation throw {@code CancellationException} and
87+ * any other I/O operations outstanding on the channel complete with the
88+ * exception {@link AsynchronousCloseException}.
89+ *
90+ * <p> Where the {@code cancel} method is invoked to cancel read or write
91+ * operations then it is recommended that all buffers used in the I/O operations
92+ * be discarded or care taken to ensure that the buffers are not accessed while
93+ * the channel remains open.
94+ *
95+ * @since 1.7
96+ */
97+
98+public interface AsynchronousChannel
99+ extends Channel
100+{
101+ /**
102+ * Closes this channel.
103+ *
104+ * <p> Any outstanding asynchronous operations upon this channel will
105+ * complete with the exception {@link AsynchronousCloseException}. After a
106+ * channel is closed, further attempts to initiate asynchronous I/O
107+ * operations complete immediately with cause {@link ClosedChannelException}.
108+ *
109+ * <p> This method otherwise behaves exactly as specified by the {@link
110+ * Channel} interface.
111+ *
112+ * @throws IOException
113+ * If an I/O error occurs
114+ */
115+ @Override
116+ void close() throws IOException;
117+}
java/pkg/java/nio/channels/AsynchronousChannelGroup.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousChannelGroup.java+344−0
@@ -0,0 +1,344 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.channels.spi.AsynchronousChannelProvider;
29+import java.io.IOException;
30+import java.util.concurrent.ExecutorService;
31+import java.util.concurrent.ThreadFactory;
32+import java.util.concurrent.TimeUnit;
33+
34+/**
35+ * A grouping of asynchronous channels for the purpose of resource sharing.
36+ *
37+ * <p> An asynchronous channel group encapsulates the mechanics required to
38+ * handle the completion of I/O operations initiated by {@link AsynchronousChannel
39+ * asynchronous channels} that are bound to the group. A group has an associated
40+ * thread pool to which tasks are submitted to handle I/O events and dispatch to
41+ * {@link CompletionHandler completion-handlers} that consume the result of
42+ * asynchronous operations performed on channels in the group. In addition to
43+ * handling I/O events, the pooled threads may also execute other tasks required
44+ * to support the execution of asynchronous I/O operations.
45+ *
46+ * <p> An asynchronous channel group is created by invoking the {@link
47+ * #withFixedThreadPool withFixedThreadPool} or {@link #withCachedThreadPool
48+ * withCachedThreadPool} methods defined here. Channels are bound to a group by
49+ * specifying the group when constructing the channel. The associated thread
50+ * pool is <em>owned</em> by the group; termination of the group results in the
51+ * shutdown of the associated thread pool.
52+ *
53+ * <p> In addition to groups created explicitly, the Java virtual machine
54+ * maintains a system-wide <em>default group</em> that is constructed
55+ * automatically. Asynchronous channels that do not specify a group at
56+ * construction time are bound to the default group. The default group has an
57+ * associated thread pool that creates new threads as needed. The default group
58+ * may be configured by means of system properties defined in the table below.
59+ * Where the {@link java.util.concurrent.ThreadFactory ThreadFactory} for the
60+ * default group is not configured then the pooled threads of the default group
61+ * are {@link Thread#isDaemon daemon} threads.
62+ *
63+ * <table border>
64+ * <tr>
65+ * <th>System property</th>
66+ * <th>Description</th>
67+ * </tr>
68+ * <tr>
69+ * <tr>
70+ * <td> {@code java.nio.channels.DefaultThreadPool.threadFactory} </td>
71+ * <td> The value of this property is taken to be the fully-qualified name
72+ * of a concrete {@link java.util.concurrent.ThreadFactory ThreadFactory}
73+ * class. The class is loaded using the system class loader and instantiated.
74+ * The factory's {@link java.util.concurrent.ThreadFactory#newThread
75+ * newThread} method is invoked to create each thread for the default
76+ * group's thread pool. If the process to load and instantiate the value
77+ * of the property fails then an unspecified error is thrown during the
78+ * construction of the default group. </td>
79+ * </tr>
80+ * <tr>
81+ * <td> {@code java.nio.channels.DefaultThreadPool.initialSize} </td>
82+ * <td> The value of the {@code initialSize} parameter for the default
83+ * group (see {@link #withCachedThreadPool withCachedThreadPool}).
84+ * The value of the property is taken to be the {@code String}
85+ * representation of an {@code Integer} that is the initial size parameter.
86+ * If the value cannot be parsed as an {@code Integer} it causes an
87+ * unspecified error to be thrown during the construction of the default
88+ * group. </td>
89+ * </tr>
90+ * </table>
91+ *
92+ * <a name="threading"><h4>Threading</h4></a>
93+ *
94+ * <p> The completion handler for an I/O operation initiated on a channel bound
95+ * to a group is guaranteed to be invoked by one of the pooled threads in the
96+ * group. This ensures that the completion handler is run by a thread with the
97+ * expected <em>identity</em>.
98+ *
99+ * <p> Where an I/O operation completes immediately, and the initiating thread
100+ * is one of the pooled threads in the group then the completion handler may
101+ * be invoked directly by the initiating thread. To avoid stack overflow, an
102+ * implementation may impose a limit as to the number of activations on the
103+ * thread stack. Some I/O operations may prohibit invoking the completion
104+ * handler directly by the initiating thread (see {@link
105+ * AsynchronousServerSocketChannel#accept(Object,CompletionHandler) accept}).
106+ *
107+ * <a name="shutdown"><h4>Shutdown and Termination</h4></a>
108+ *
109+ * <p> The {@link #shutdown() shutdown} method is used to initiate an <em>orderly
110+ * shutdown</em> of a group. An orderly shutdown marks the group as shutdown;
111+ * further attempts to construct a channel that binds to the group will throw
112+ * {@link ShutdownChannelGroupException}. Whether or not a group is shutdown can
113+ * be tested using the {@link #isShutdown() isShutdown} method. Once shutdown,
114+ * the group <em>terminates</em> when all asynchronous channels that are bound to
115+ * the group are closed, all actively executing completion handlers have run to
116+ * completion, and resources used by the group are released. No attempt is made
117+ * to stop or interrupt threads that are executing completion handlers. The
118+ * {@link #isTerminated() isTerminated} method is used to test if the group has
119+ * terminated, and the {@link #awaitTermination awaitTermination} method can be
120+ * used to block until the group has terminated.
121+ *
122+ * <p> The {@link #shutdownNow() shutdownNow} method can be used to initiate a
123+ * <em>forceful shutdown</em> of the group. In addition to the actions performed
124+ * by an orderly shutdown, the {@code shutdownNow} method closes all open channels
125+ * in the group as if by invoking the {@link AsynchronousChannel#close close}
126+ * method.
127+ *
128+ * @since 1.7
129+ *
130+ * @see AsynchronousSocketChannel#open(AsynchronousChannelGroup)
131+ * @see AsynchronousServerSocketChannel#open(AsynchronousChannelGroup)
132+ */
133+
134+public abstract class AsynchronousChannelGroup {
135+ private final AsynchronousChannelProvider provider;
136+
137+ /**
138+ * Initialize a new instance of this class.
139+ *
140+ * @param provider
141+ * The asynchronous channel provider for this group
142+ */
143+ protected AsynchronousChannelGroup(AsynchronousChannelProvider provider) {
144+ this.provider = provider;
145+ }
146+
147+ /**
148+ * Returns the provider that created this channel group.
149+ *
150+ * @return The provider that created this channel group
151+ */
152+ public final AsynchronousChannelProvider provider() {
153+ return provider;
154+ }
155+
156+ /**
157+ * Creates an asynchronous channel group with a fixed thread pool.
158+ *
159+ * <p> The resulting asynchronous channel group reuses a fixed number of
160+ * threads. At any point, at most {@code nThreads} threads will be active
161+ * processing tasks that are submitted to handle I/O events and dispatch
162+ * completion results for operations initiated on asynchronous channels in
163+ * the group.
164+ *
165+ * <p> The group is created by invoking the {@link
166+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(int,ThreadFactory)
167+ * openAsynchronousChannelGroup(int,ThreadFactory)} method of the system-wide
168+ * default {@link AsynchronousChannelProvider} object.
169+ *
170+ * @param nThreads
171+ * The number of threads in the pool
172+ * @param threadFactory
173+ * The factory to use when creating new threads
174+ *
175+ * @return A new asynchronous channel group
176+ *
177+ * @throws IllegalArgumentException
178+ * If {@code nThreads <= 0}
179+ * @throws IOException
180+ * If an I/O error occurs
181+ */
182+ public static AsynchronousChannelGroup withFixedThreadPool(int nThreads,
183+ ThreadFactory threadFactory)
184+ throws IOException
185+ {
186+ return AsynchronousChannelProvider.provider()
187+ .openAsynchronousChannelGroup(nThreads, threadFactory);
188+ }
189+
190+ /**
191+ * Creates an asynchronous channel group with a given thread pool that
192+ * creates new threads as needed.
193+ *
194+ * <p> The {@code executor} parameter is an {@code ExecutorService} that
195+ * creates new threads as needed to execute tasks that are submitted to
196+ * handle I/O events and dispatch completion results for operations initiated
197+ * on asynchronous channels in the group. It may reuse previously constructed
198+ * threads when they are available.
199+ *
200+ * <p> The {@code initialSize} parameter may be used by the implementation
201+ * as a <em>hint</em> as to the initial number of tasks it may submit. For
202+ * example, it may be used to indictae the initial number of threads that
203+ * wait on I/O events.
204+ *
205+ * <p> The executor is intended to be used exclusively by the resulting
206+ * asynchronous channel group. Termination of the group results in the
207+ * orderly {@link ExecutorService#shutdown shutdown} of the executor
208+ * service. Shutting down the executor service by other means results in
209+ * unspecified behavior.
210+ *
211+ * <p> The group is created by invoking the {@link
212+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
213+ * openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
214+ * default {@link AsynchronousChannelProvider} object.
215+ *
216+ * @param executor
217+ * The thread pool for the resulting group
218+ * @param initialSize
219+ * A value {@code >=0} or a negative value for implementation
220+ * specific default
221+ *
222+ * @return A new asynchronous channel group
223+ *
224+ * @throws IOException
225+ * If an I/O error occurs
226+ *
227+ * @see java.util.concurrent.Executors#newCachedThreadPool
228+ */
229+ public static AsynchronousChannelGroup withCachedThreadPool(ExecutorService executor,
230+ int initialSize)
231+ throws IOException
232+ {
233+ return AsynchronousChannelProvider.provider()
234+ .openAsynchronousChannelGroup(executor, initialSize);
235+ }
236+
237+ /**
238+ * Creates an asynchronous channel group with a given thread pool.
239+ *
240+ * <p> The {@code executor} parameter is an {@code ExecutorService} that
241+ * executes tasks submitted to dispatch completion results for operations
242+ * initiated on asynchronous channels in the group.
243+ *
244+ * <p> Care should be taken when configuring the executor service. It
245+ * should support <em>direct handoff</em> or <em>unbounded queuing</em> of
246+ * submitted tasks, and the thread that invokes the {@link
247+ * ExecutorService#execute execute} method should never invoke the task
248+ * directly. An implementation may mandate additional constraints.
249+ *
250+ * <p> The executor is intended to be used exclusively by the resulting
251+ * asynchronous channel group. Termination of the group results in the
252+ * orderly {@link ExecutorService#shutdown shutdown} of the executor
253+ * service. Shutting down the executor service by other means results in
254+ * unspecified behavior.
255+ *
256+ * <p> The group is created by invoking the {@link
257+ * AsynchronousChannelProvider#openAsynchronousChannelGroup(ExecutorService,int)
258+ * openAsynchronousChannelGroup(ExecutorService,int)} method of the system-wide
259+ * default {@link AsynchronousChannelProvider} object with an {@code
260+ * initialSize} of {@code 0}.
261+ *
262+ * @param executor
263+ * The thread pool for the resulting group
264+ *
265+ * @return A new asynchronous channel group
266+ *
267+ * @throws IOException
268+ * If an I/O error occurs
269+ */
270+ public static AsynchronousChannelGroup withThreadPool(ExecutorService executor)
271+ throws IOException
272+ {
273+ return AsynchronousChannelProvider.provider()
274+ .openAsynchronousChannelGroup(executor, 0);
275+ }
276+
277+ /**
278+ * Tells whether or not this asynchronous channel group is shutdown.
279+ *
280+ * @return {@code true} if this asynchronous channel group is shutdown or
281+ * has been marked for shutdown.
282+ */
283+ public abstract boolean isShutdown();
284+
285+ /**
286+ * Tells whether or not this group has terminated.
287+ *
288+ * <p> Where this method returns {@code true}, then the associated thread
289+ * pool has also {@link ExecutorService#isTerminated terminated}.
290+ *
291+ * @return {@code true} if this group has terminated
292+ */
293+ public abstract boolean isTerminated();
294+
295+ /**
296+ * Initiates an orderly shutdown of the group.
297+ *
298+ * <p> This method marks the group as shutdown. Further attempts to construct
299+ * channel that binds to this group will throw {@link ShutdownChannelGroupException}.
300+ * The group terminates when all asynchronous channels in the group are
301+ * closed, all actively executing completion handlers have run to completion,
302+ * and all resources have been released. This method has no effect if the
303+ * group is already shutdown.
304+ */
305+ public abstract void shutdown();
306+
307+ /**
308+ * Shuts down the group and closes all open channels in the group.
309+ *
310+ * <p> In addition to the actions performed by the {@link #shutdown() shutdown}
311+ * method, this method invokes the {@link AsynchronousChannel#close close}
312+ * method on all open channels in the group. This method does not attempt to
313+ * stop or interrupt threads that are executing completion handlers. The
314+ * group terminates when all actively executing completion handlers have run
315+ * to completion and all resources have been released. This method may be
316+ * invoked at any time. If some other thread has already invoked it, then
317+ * another invocation will block until the first invocation is complete,
318+ * after which it will return without effect.
319+ *
320+ * @throws IOException
321+ * If an I/O error occurs
322+ */
323+ public abstract void shutdownNow() throws IOException;
324+
325+ /**
326+ * Awaits termination of the group.
327+
328+ * <p> This method blocks until the group has terminated, or the timeout
329+ * occurs, or the current thread is interrupted, whichever happens first.
330+ *
331+ * @param timeout
332+ * The maximum time to wait, or zero or less to not wait
333+ * @param unit
334+ * The time unit of the timeout argument
335+ *
336+ * @return {@code true} if the group has terminated; {@code false} if the
337+ * timeout elapsed before termination
338+ *
339+ * @throws InterruptedException
340+ * If interrupted while waiting
341+ */
342+ public abstract boolean awaitTermination(long timeout, TimeUnit unit)
343+ throws InterruptedException;
344+}
java/pkg/java/nio/channels/AsynchronousFileChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousFileChannel.java+770−0
@@ -0,0 +1,770 @@
1+/*
2+ * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.file.*;
29+import java.nio.file.attribute.FileAttribute;
30+import java.nio.file.spi.*;
31+import java.nio.ByteBuffer;
32+import java.io.IOException;
33+import java.util.concurrent.Future;
34+import java.util.concurrent.ExecutorService;
35+import java.util.Set;
36+import java.util.HashSet;
37+import java.util.Collections;
38+
39+/**
40+ * An asynchronous channel for reading, writing, and manipulating a file.
41+ *
42+ * <p> An asynchronous file channel is created when a file is opened by invoking
43+ * one of the {@link #open open} methods defined by this class. The file contains
44+ * a variable-length sequence of bytes that can be read and written and whose
45+ * current size can be {@link #size() queried}. The size of the file increases
46+ * when bytes are written beyond its current size; the size of the file decreases
47+ * when it is {@link #truncate truncated}.
48+ *
49+ * <p> An asynchronous file channel does not have a <i>current position</i>
50+ * within the file. Instead, the file position is specified to each read and
51+ * write method that initiates asynchronous operations. A {@link CompletionHandler}
52+ * is specified as a parameter and is invoked to consume the result of the I/O
53+ * operation. This class also defines read and write methods that initiate
54+ * asynchronous operations, returning a {@link Future} to represent the pending
55+ * result of the operation. The {@code Future} may be used to check if the
56+ * operation has completed, wait for its completion, and retrieve the result.
57+ *
58+ * <p> In addition to read and write operations, this class defines the
59+ * following operations: </p>
60+ *
61+ * <ul>
62+ *
63+ * <li><p> Updates made to a file may be {@link #force <i>forced
64+ * out</i>} to the underlying storage device, ensuring that data are not
65+ * lost in the event of a system crash. </p></li>
66+ *
67+ * <li><p> A region of a file may be {@link #lock <i>locked</i>} against
68+ * access by other programs. </p></li>
69+ *
70+ * </ul>
71+ *
72+ * <p> An {@code AsynchronousFileChannel} is associated with a thread pool to
73+ * which tasks are submitted to handle I/O events and dispatch to completion
74+ * handlers that consume the results of I/O operations on the channel. The
75+ * completion handler for an I/O operation initiated on a channel is guaranteed
76+ * to be invoked by one of the threads in the thread pool (This ensures that the
77+ * completion handler is run by a thread with the expected <em>identity</em>).
78+ * Where an I/O operation completes immediately, and the initiating thread is
79+ * itself a thread in the thread pool, then the completion handler may be invoked
80+ * directly by the initiating thread. When an {@code AsynchronousFileChannel} is
81+ * created without specifying a thread pool then the channel is associated with
82+ * a system-dependent default thread pool that may be shared with other
83+ * channels. The default thread pool is configured by the system properties
84+ * defined by the {@link AsynchronousChannelGroup} class.
85+ *
86+ * <p> Channels of this type are safe for use by multiple concurrent threads. The
87+ * {@link Channel#close close} method may be invoked at any time, as specified
88+ * by the {@link Channel} interface. This causes all outstanding asynchronous
89+ * operations on the channel to complete with the exception {@link
90+ * AsynchronousCloseException}. Multiple read and write operations may be
91+ * outstanding at the same time. When multiple read and write operations are
92+ * outstanding then the ordering of the I/O operations, and the order that the
93+ * completion handlers are invoked, is not specified; they are not, in particular,
94+ * guaranteed to execute in the order that the operations were initiated. The
95+ * {@link java.nio.ByteBuffer ByteBuffers} used when reading or writing are not
96+ * safe for use by multiple concurrent I/O operations. Furthermore, after an I/O
97+ * operation is initiated then care should be taken to ensure that the buffer is
98+ * not accessed until after the operation has completed.
99+ *
100+ * <p> As with {@link FileChannel}, the view of a file provided by an instance of
101+ * this class is guaranteed to be consistent with other views of the same file
102+ * provided by other instances in the same program. The view provided by an
103+ * instance of this class may or may not, however, be consistent with the views
104+ * seen by other concurrently-running programs due to caching performed by the
105+ * underlying operating system and delays induced by network-filesystem protocols.
106+ * This is true regardless of the language in which these other programs are
107+ * written, and whether they are running on the same machine or on some other
108+ * machine. The exact nature of any such inconsistencies are system-dependent
109+ * and are therefore unspecified.
110+ *
111+ * @since 1.7
112+ */
113+
114+public abstract class AsynchronousFileChannel
115+ implements AsynchronousChannel
116+{
117+ /**
118+ * Initializes a new instance of this class.
119+ */
120+ protected AsynchronousFileChannel() {
121+ }
122+
123+ /**
124+ * Opens or creates a file for reading and/or writing, returning an
125+ * asynchronous file channel to access the file.
126+ *
127+ * <p> The {@code options} parameter determines how the file is opened.
128+ * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
129+ * WRITE} options determines if the file should be opened for reading and/or
130+ * writing. If neither option is contained in the array then an existing file
131+ * is opened for reading.
132+ *
133+ * <p> In addition to {@code READ} and {@code WRITE}, the following options
134+ * may be present:
135+ *
136+ * <table border=1 cellpadding=5 summary="">
137+ * <tr> <th>Option</th> <th>Description</th> </tr>
138+ * <tr>
139+ * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
140+ * <td> When opening an existing file, the file is first truncated to a
141+ * size of 0 bytes. This option is ignored when the file is opened only
142+ * for reading.</td>
143+ * </tr>
144+ * <tr>
145+ * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
146+ * <td> If this option is present then a new file is created, failing if
147+ * the file already exists. When creating a file the check for the
148+ * existence of the file and the creation of the file if it does not exist
149+ * is atomic with respect to other file system operations. This option is
150+ * ignored when the file is opened only for reading. </td>
151+ * </tr>
152+ * <tr>
153+ * <td > {@link StandardOpenOption#CREATE CREATE} </td>
154+ * <td> If this option is present then an existing file is opened if it
155+ * exists, otherwise a new file is created. When creating a file the check
156+ * for the existence of the file and the creation of the file if it does
157+ * not exist is atomic with respect to other file system operations. This
158+ * option is ignored if the {@code CREATE_NEW} option is also present or
159+ * the file is opened only for reading. </td>
160+ * </tr>
161+ * <tr>
162+ * <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>
163+ * <td> When this option is present then the implementation makes a
164+ * <em>best effort</em> attempt to delete the file when closed by the
165+ * the {@link #close close} method. If the {@code close} method is not
166+ * invoked then a <em>best effort</em> attempt is made to delete the file
167+ * when the Java virtual machine terminates. </td>
168+ * </tr>
169+ * <tr>
170+ * <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
171+ * <td> When creating a new file this option is a <em>hint</em> that the
172+ * new file will be sparse. This option is ignored when not creating
173+ * a new file. </td>
174+ * </tr>
175+ * <tr>
176+ * <td> {@link StandardOpenOption#SYNC SYNC} </td>
177+ * <td> Requires that every update to the file's content or metadata be
178+ * written synchronously to the underlying storage device. (see <a
179+ * href="../file/package-summary.html#integrity"> Synchronized I/O file
180+ * integrity</a>). </td>
181+ * <tr>
182+ * <tr>
183+ * <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
184+ * <td> Requires that every update to the file's content be written
185+ * synchronously to the underlying storage device. (see <a
186+ * href="../file/package-summary.html#integrity"> Synchronized I/O file
187+ * integrity</a>). </td>
188+ * </tr>
189+ * </table>
190+ *
191+ * <p> An implementation may also support additional options.
192+ *
193+ * <p> The {@code executor} parameter is the {@link ExecutorService} to
194+ * which tasks are submitted to handle I/O events and dispatch completion
195+ * results for operations initiated on resulting channel.
196+ * The nature of these tasks is highly implementation specific and so care
197+ * should be taken when configuring the {@code Executor}. Minimally it
198+ * should support an unbounded work queue and should not run tasks on the
199+ * caller thread of the {@link ExecutorService#execute execute} method.
200+ * Shutting down the executor service while the channel is open results in
201+ * unspecified behavior.
202+ *
203+ * <p> The {@code attrs} parameter is an optional array of file {@link
204+ * FileAttribute file-attributes} to set atomically when creating the file.
205+ *
206+ * <p> The new channel is created by invoking the {@link
207+ * FileSystemProvider#newFileChannel newFileChannel} method on the
208+ * provider that created the {@code Path}.
209+ *
210+ * @param file
211+ * The path of the file to open or create
212+ * @param options
213+ * Options specifying how the file is opened
214+ * @param executor
215+ * The thread pool or {@code null} to associate the channel with
216+ * the default thread pool
217+ * @param attrs
218+ * An optional list of file attributes to set atomically when
219+ * creating the file
220+ *
221+ * @return A new asynchronous file channel
222+ *
223+ * @throws IllegalArgumentException
224+ * If the set contains an invalid combination of options
225+ * @throws UnsupportedOperationException
226+ * If the {@code file} is associated with a provider that does not
227+ * support creating asynchronous file channels, or an unsupported
228+ * open option is specified, or the array contains an attribute that
229+ * cannot be set atomically when creating the file
230+ * @throws IOException
231+ * If an I/O error occurs
232+ * @throws SecurityException
233+ * If a security manager is installed and it denies an
234+ * unspecified permission required by the implementation.
235+ * In the case of the default provider, the {@link
236+ * SecurityManager#checkRead(String)} method is invoked to check
237+ * read access if the file is opened for reading. The {@link
238+ * SecurityManager#checkWrite(String)} method is invoked to check
239+ * write access if the file is opened for writing
240+ */
241+ public static AsynchronousFileChannel open(Path file,
242+ Set<? extends OpenOption> options,
243+ ExecutorService executor,
244+ FileAttribute<?>... attrs)
245+ throws IOException
246+ {
247+ FileSystemProvider provider = file.getFileSystem().provider();
248+ return provider.newAsynchronousFileChannel(file, options, executor, attrs);
249+ }
250+
251+ private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0];
252+
253+ /**
254+ * Opens or creates a file for reading and/or writing, returning an
255+ * asynchronous file channel to access the file.
256+ *
257+ * <p> An invocation of this method behaves in exactly the same way as the
258+ * invocation
259+ * <pre>
260+ * ch.{@link #open(Path,Set,ExecutorService,FileAttribute[])
261+ * open}(file, opts, null, new FileAttribute&lt;?&gt;[0]);
262+ * </pre>
263+ * where {@code opts} is a {@code Set} containing the options specified to
264+ * this method.
265+ *
266+ * <p> The resulting channel is associated with default thread pool to which
267+ * tasks are submitted to handle I/O events and dispatch to completion
268+ * handlers that consume the result of asynchronous operations performed on
269+ * the resulting channel.
270+ *
271+ * @param file
272+ * The path of the file to open or create
273+ * @param options
274+ * Options specifying how the file is opened
275+ *
276+ * @return A new asynchronous file channel
277+ *
278+ * @throws IllegalArgumentException
279+ * If the set contains an invalid combination of options
280+ * @throws UnsupportedOperationException
281+ * If the {@code file} is associated with a provider that does not
282+ * support creating file channels, or an unsupported open option is
283+ * specified
284+ * @throws IOException
285+ * If an I/O error occurs
286+ * @throws SecurityException
287+ * If a security manager is installed and it denies an
288+ * unspecified permission required by the implementation.
289+ * In the case of the default provider, the {@link
290+ * SecurityManager#checkRead(String)} method is invoked to check
291+ * read access if the file is opened for reading. The {@link
292+ * SecurityManager#checkWrite(String)} method is invoked to check
293+ * write access if the file is opened for writing
294+ */
295+ public static AsynchronousFileChannel open(Path file, OpenOption... options)
296+ throws IOException
297+ {
298+ Set<OpenOption> set = new HashSet<OpenOption>(options.length);
299+ Collections.addAll(set, options);
300+ return open(file, set, null, NO_ATTRIBUTES);
301+ }
302+
303+ /**
304+ * Returns the current size of this channel's file.
305+ *
306+ * @return The current size of this channel's file, measured in bytes
307+ *
308+ * @throws ClosedChannelException
309+ * If this channel is closed
310+ * @throws IOException
311+ * If some other I/O error occurs
312+ */
313+ public abstract long size() throws IOException;
314+
315+ /**
316+ * Truncates this channel's file to the given size.
317+ *
318+ * <p> If the given size is less than the file's current size then the file
319+ * is truncated, discarding any bytes beyond the new end of the file. If
320+ * the given size is greater than or equal to the file's current size then
321+ * the file is not modified. </p>
322+ *
323+ * @param size
324+ * The new size, a non-negative byte count
325+ *
326+ * @return This file channel
327+ *
328+ * @throws NonWritableChannelException
329+ * If this channel was not opened for writing
330+ *
331+ * @throws ClosedChannelException
332+ * If this channel is closed
333+ *
334+ * @throws IllegalArgumentException
335+ * If the new size is negative
336+ *
337+ * @throws IOException
338+ * If some other I/O error occurs
339+ */
340+ public abstract AsynchronousFileChannel truncate(long size) throws IOException;
341+
342+ /**
343+ * Forces any updates to this channel's file to be written to the storage
344+ * device that contains it.
345+ *
346+ * <p> If this channel's file resides on a local storage device then when
347+ * this method returns it is guaranteed that all changes made to the file
348+ * since this channel was created, or since this method was last invoked,
349+ * will have been written to that device. This is useful for ensuring that
350+ * critical information is not lost in the event of a system crash.
351+ *
352+ * <p> If the file does not reside on a local device then no such guarantee
353+ * is made.
354+ *
355+ * <p> The {@code metaData} parameter can be used to limit the number of
356+ * I/O operations that this method is required to perform. Passing
357+ * {@code false} for this parameter indicates that only updates to the
358+ * file's content need be written to storage; passing {@code true}
359+ * indicates that updates to both the file's content and metadata must be
360+ * written, which generally requires at least one more I/O operation.
361+ * Whether this parameter actually has any effect is dependent upon the
362+ * underlying operating system and is therefore unspecified.
363+ *
364+ * <p> Invoking this method may cause an I/O operation to occur even if the
365+ * channel was only opened for reading. Some operating systems, for
366+ * example, maintain a last-access time as part of a file's metadata, and
367+ * this time is updated whenever the file is read. Whether or not this is
368+ * actually done is system-dependent and is therefore unspecified.
369+ *
370+ * <p> This method is only guaranteed to force changes that were made to
371+ * this channel's file via the methods defined in this class.
372+ *
373+ * @param metaData
374+ * If {@code true} then this method is required to force changes
375+ * to both the file's content and metadata to be written to
376+ * storage; otherwise, it need only force content changes to be
377+ * written
378+ *
379+ * @throws ClosedChannelException
380+ * If this channel is closed
381+ *
382+ * @throws IOException
383+ * If some other I/O error occurs
384+ */
385+ public abstract void force(boolean metaData) throws IOException;
386+
387+ /**
388+ * Acquires a lock on the given region of this channel's file.
389+ *
390+ * <p> This method initiates an operation to acquire a lock on the given
391+ * region of this channel's file. The {@code handler} parameter is a
392+ * completion handler that is invoked when the lock is acquired (or the
393+ * operation fails). The result passed to the completion handler is the
394+ * resulting {@code FileLock}.
395+ *
396+ * <p> The region specified by the {@code position} and {@code size}
397+ * parameters need not be contained within, or even overlap, the actual
398+ * underlying file. Lock regions are fixed in size; if a locked region
399+ * initially contains the end of the file and the file grows beyond the
400+ * region then the new portion of the file will not be covered by the lock.
401+ * If a file is expected to grow in size and a lock on the entire file is
402+ * required then a region starting at zero, and no smaller than the
403+ * expected maximum size of the file, should be locked. The two-argument
404+ * {@link #lock(Object,CompletionHandler)} method simply locks a region
405+ * of size {@link Long#MAX_VALUE}. If a lock that overlaps the requested
406+ * region is already held by this Java virtual machine, or this method has
407+ * been invoked to lock an overlapping region and that operation has not
408+ * completed, then this method throws {@link OverlappingFileLockException}.
409+ *
410+ * <p> Some operating systems do not support a mechanism to acquire a file
411+ * lock in an asynchronous manner. Consequently an implementation may
412+ * acquire the file lock in a background thread or from a task executed by
413+ * a thread in the associated thread pool. If there are many lock operations
414+ * outstanding then it may consume threads in the Java virtual machine for
415+ * indefinite periods.
416+ *
417+ * <p> Some operating systems do not support shared locks, in which case a
418+ * request for a shared lock is automatically converted into a request for
419+ * an exclusive lock. Whether the newly-acquired lock is shared or
420+ * exclusive may be tested by invoking the resulting lock object's {@link
421+ * FileLock#isShared() isShared} method.
422+ *
423+ * <p> File locks are held on behalf of the entire Java virtual machine.
424+ * They are not suitable for controlling access to a file by multiple
425+ * threads within the same virtual machine.
426+ *
427+ * @param position
428+ * The position at which the locked region is to start; must be
429+ * non-negative
430+ * @param size
431+ * The size of the locked region; must be non-negative, and the sum
432+ * {@code position}&nbsp;+&nbsp;{@code size} must be non-negative
433+ * @param shared
434+ * {@code true} to request a shared lock, in which case this
435+ * channel must be open for reading (and possibly writing);
436+ * {@code false} to request an exclusive lock, in which case this
437+ * channel must be open for writing (and possibly reading)
438+ * @param attachment
439+ * The object to attach to the I/O operation; can be {@code null}
440+ * @param handler
441+ * The handler for consuming the result
442+ *
443+ * @throws OverlappingFileLockException
444+ * If a lock that overlaps the requested region is already held by
445+ * this Java virtual machine, or there is already a pending attempt
446+ * to lock an overlapping region
447+ * @throws IllegalArgumentException
448+ * If the preconditions on the parameters do not hold
449+ * @throws NonReadableChannelException
450+ * If {@code shared} is true but this channel was not opened for reading
451+ * @throws NonWritableChannelException
452+ * If {@code shared} is false but this channel was not opened for writing
453+ */
454+ public abstract <A> void lock(long position,
455+ long size,
456+ boolean shared,
457+ A attachment,
458+ CompletionHandler<FileLock,? super A> handler);
459+
460+ /**
461+ * Acquires an exclusive lock on this channel's file.
462+ *
463+ * <p> This method initiates an operation to acquire a lock on the given
464+ * region of this channel's file. The {@code handler} parameter is a
465+ * completion handler that is invoked when the lock is acquired (or the
466+ * operation fails). The result passed to the completion handler is the
467+ * resulting {@code FileLock}.
468+ *
469+ * <p> An invocation of this method of the form {@code ch.lock(att,handler)}
470+ * behaves in exactly the same way as the invocation
471+ * <pre>
472+ * ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)
473+ * </pre>
474+ *
475+ * @param attachment
476+ * The object to attach to the I/O operation; can be {@code null}
477+ * @param handler
478+ * The handler for consuming the result
479+ *
480+ * @throws OverlappingFileLockException
481+ * If a lock is already held by this Java virtual machine, or there
482+ * is already a pending attempt to lock a region
483+ * @throws NonWritableChannelException
484+ * If this channel was not opened for writing
485+ */
486+ public final <A> void lock(A attachment,
487+ CompletionHandler<FileLock,? super A> handler)
488+ {
489+ lock(0L, Long.MAX_VALUE, false, attachment, handler);
490+ }
491+
492+ /**
493+ * Acquires a lock on the given region of this channel's file.
494+ *
495+ * <p> This method initiates an operation to acquire a lock on the given
496+ * region of this channel's file. The method behaves in exactly the same
497+ * manner as the {@link #lock(long, long, boolean, Object, CompletionHandler)}
498+ * method except that instead of specifying a completion handler, this
499+ * method returns a {@code Future} representing the pending result. The
500+ * {@code Future}'s {@link Future#get() get} method returns the {@link
501+ * FileLock} on successful completion.
502+ *
503+ * @param position
504+ * The position at which the locked region is to start; must be
505+ * non-negative
506+ * @param size
507+ * The size of the locked region; must be non-negative, and the sum
508+ * {@code position}&nbsp;+&nbsp;{@code size} must be non-negative
509+ * @param shared
510+ * {@code true} to request a shared lock, in which case this
511+ * channel must be open for reading (and possibly writing);
512+ * {@code false} to request an exclusive lock, in which case this
513+ * channel must be open for writing (and possibly reading)
514+ *
515+ * @return a {@code Future} object representing the pending result
516+ *
517+ * @throws OverlappingFileLockException
518+ * If a lock is already held by this Java virtual machine, or there
519+ * is already a pending attempt to lock a region
520+ * @throws IllegalArgumentException
521+ * If the preconditions on the parameters do not hold
522+ * @throws NonReadableChannelException
523+ * If {@code shared} is true but this channel was not opened for reading
524+ * @throws NonWritableChannelException
525+ * If {@code shared} is false but this channel was not opened for writing
526+ */
527+ public abstract Future<FileLock> lock(long position, long size, boolean shared);
528+
529+ /**
530+ * Acquires an exclusive lock on this channel's file.
531+ *
532+ * <p> This method initiates an operation to acquire an exclusive lock on this
533+ * channel's file. The method returns a {@code Future} representing the
534+ * pending result of the operation. The {@code Future}'s {@link Future#get()
535+ * get} method returns the {@link FileLock} on successful completion.
536+ *
537+ * <p> An invocation of this method behaves in exactly the same way as the
538+ * invocation
539+ * <pre>
540+ * ch.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false)
541+ * </pre>
542+ *
543+ * @return a {@code Future} object representing the pending result
544+ *
545+ * @throws OverlappingFileLockException
546+ * If a lock is already held by this Java virtual machine, or there
547+ * is already a pending attempt to lock a region
548+ * @throws NonWritableChannelException
549+ * If this channel was not opened for writing
550+ */
551+ public final Future<FileLock> lock() {
552+ return lock(0L, Long.MAX_VALUE, false);
553+ }
554+
555+ /**
556+ * Attempts to acquire a lock on the given region of this channel's file.
557+ *
558+ * <p> This method does not block. An invocation always returns immediately,
559+ * either having acquired a lock on the requested region or having failed to
560+ * do so. If it fails to acquire a lock because an overlapping lock is held
561+ * by another program then it returns {@code null}. If it fails to acquire
562+ * a lock for any other reason then an appropriate exception is thrown.
563+ *
564+ * @param position
565+ * The position at which the locked region is to start; must be
566+ * non-negative
567+ *
568+ * @param size
569+ * The size of the locked region; must be non-negative, and the sum
570+ * {@code position}&nbsp;+&nbsp;{@code size} must be non-negative
571+ *
572+ * @param shared
573+ * {@code true} to request a shared lock,
574+ * {@code false} to request an exclusive lock
575+ *
576+ * @return A lock object representing the newly-acquired lock,
577+ * or {@code null} if the lock could not be acquired
578+ * because another program holds an overlapping lock
579+ *
580+ * @throws IllegalArgumentException
581+ * If the preconditions on the parameters do not hold
582+ * @throws ClosedChannelException
583+ * If this channel is closed
584+ * @throws OverlappingFileLockException
585+ * If a lock that overlaps the requested region is already held by
586+ * this Java virtual machine, or if another thread is already
587+ * blocked in this method and is attempting to lock an overlapping
588+ * region of the same file
589+ * @throws NonReadableChannelException
590+ * If {@code shared} is true but this channel was not opened for reading
591+ * @throws NonWritableChannelException
592+ * If {@code shared} is false but this channel was not opened for writing
593+ *
594+ * @throws IOException
595+ * If some other I/O error occurs
596+ *
597+ * @see #lock(Object,CompletionHandler)
598+ * @see #lock(long,long,boolean,Object,CompletionHandler)
599+ * @see #tryLock()
600+ */
601+ public abstract FileLock tryLock(long position, long size, boolean shared)
602+ throws IOException;
603+
604+ /**
605+ * Attempts to acquire an exclusive lock on this channel's file.
606+ *
607+ * <p> An invocation of this method of the form {@code ch.tryLock()}
608+ * behaves in exactly the same way as the invocation
609+ *
610+ * <pre>
611+ * ch.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
612+ *
613+ * @return A lock object representing the newly-acquired lock,
614+ * or {@code null} if the lock could not be acquired
615+ * because another program holds an overlapping lock
616+ *
617+ * @throws ClosedChannelException
618+ * If this channel is closed
619+ * @throws OverlappingFileLockException
620+ * If a lock that overlaps the requested region is already held by
621+ * this Java virtual machine, or if another thread is already
622+ * blocked in this method and is attempting to lock an overlapping
623+ * region
624+ * @throws NonWritableChannelException
625+ * If {@code shared} is false but this channel was not opened for writing
626+ *
627+ * @throws IOException
628+ * If some other I/O error occurs
629+ *
630+ * @see #lock(Object,CompletionHandler)
631+ * @see #lock(long,long,boolean,Object,CompletionHandler)
632+ * @see #tryLock(long,long,boolean)
633+ */
634+ public final FileLock tryLock() throws IOException {
635+ return tryLock(0L, Long.MAX_VALUE, false);
636+ }
637+
638+ /**
639+ * Reads a sequence of bytes from this channel into the given buffer,
640+ * starting at the given file position.
641+ *
642+ * <p> This method initiates the reading of a sequence of bytes from this
643+ * channel into the given buffer, starting at the given file position. The
644+ * result of the read is the number of bytes read or {@code -1} if the given
645+ * position is greater than or equal to the file's size at the time that the
646+ * read is attempted.
647+ *
648+ * <p> This method works in the same manner as the {@link
649+ * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
650+ * method, except that bytes are read starting at the given file position.
651+ * If the given file position is greater than the file's size at the time
652+ * that the read is attempted then no bytes are read.
653+ *
654+ * @param dst
655+ * The buffer into which bytes are to be transferred
656+ * @param position
657+ * The file position at which the transfer is to begin;
658+ * must be non-negative
659+ * @param attachment
660+ * The object to attach to the I/O operation; can be {@code null}
661+ * @param handler
662+ * The handler for consuming the result
663+ *
664+ * @throws IllegalArgumentException
665+ * If the position is negative or the buffer is read-only
666+ * @throws NonReadableChannelException
667+ * If this channel was not opened for reading
668+ */
669+ public abstract <A> void read(ByteBuffer dst,
670+ long position,
671+ A attachment,
672+ CompletionHandler<Integer,? super A> handler);
673+
674+ /**
675+ * Reads a sequence of bytes from this channel into the given buffer,
676+ * starting at the given file position.
677+ *
678+ * <p> This method initiates the reading of a sequence of bytes from this
679+ * channel into the given buffer, starting at the given file position. This
680+ * method returns a {@code Future} representing the pending result of the
681+ * operation. The {@code Future}'s {@link Future#get() get} method returns
682+ * the number of bytes read or {@code -1} if the given position is greater
683+ * than or equal to the file's size at the time that the read is attempted.
684+ *
685+ * <p> This method works in the same manner as the {@link
686+ * AsynchronousByteChannel#read(ByteBuffer)} method, except that bytes are
687+ * read starting at the given file position. If the given file position is
688+ * greater than the file's size at the time that the read is attempted then
689+ * no bytes are read.
690+ *
691+ * @param dst
692+ * The buffer into which bytes are to be transferred
693+ * @param position
694+ * The file position at which the transfer is to begin;
695+ * must be non-negative
696+ *
697+ * @return A {@code Future} object representing the pending result
698+ *
699+ * @throws IllegalArgumentException
700+ * If the position is negative or the buffer is read-only
701+ * @throws NonReadableChannelException
702+ * If this channel was not opened for reading
703+ */
704+ public abstract Future<Integer> read(ByteBuffer dst, long position);
705+
706+ /**
707+ * Writes a sequence of bytes to this channel from the given buffer, starting
708+ * at the given file position.
709+ *
710+ * <p> This method works in the same manner as the {@link
711+ * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
712+ * method, except that bytes are written starting at the given file position.
713+ * If the given position is greater than the file's size, at the time that
714+ * the write is attempted, then the file will be grown to accommodate the new
715+ * bytes; the values of any bytes between the previous end-of-file and the
716+ * newly-written bytes are unspecified.
717+ *
718+ * @param src
719+ * The buffer from which bytes are to be transferred
720+ * @param position
721+ * The file position at which the transfer is to begin;
722+ * must be non-negative
723+ * @param attachment
724+ * The object to attach to the I/O operation; can be {@code null}
725+ * @param handler
726+ * The handler for consuming the result
727+ *
728+ * @throws IllegalArgumentException
729+ * If the position is negative
730+ * @throws NonWritableChannelException
731+ * If this channel was not opened for writing
732+ */
733+ public abstract <A> void write(ByteBuffer src,
734+ long position,
735+ A attachment,
736+ CompletionHandler<Integer,? super A> handler);
737+
738+ /**
739+ * Writes a sequence of bytes to this channel from the given buffer, starting
740+ * at the given file position.
741+ *
742+ * <p> This method initiates the writing of a sequence of bytes to this
743+ * channel from the given buffer, starting at the given file position. The
744+ * method returns a {@code Future} representing the pending result of the
745+ * write operation. The {@code Future}'s {@link Future#get() get} method
746+ * returns the number of bytes written.
747+ *
748+ * <p> This method works in the same manner as the {@link
749+ * AsynchronousByteChannel#write(ByteBuffer)} method, except that bytes are
750+ * written starting at the given file position. If the given position is
751+ * greater than the file's size, at the time that the write is attempted,
752+ * then the file will be grown to accommodate the new bytes; the values of
753+ * any bytes between the previous end-of-file and the newly-written bytes
754+ * are unspecified.
755+ *
756+ * @param src
757+ * The buffer from which bytes are to be transferred
758+ * @param position
759+ * The file position at which the transfer is to begin;
760+ * must be non-negative
761+ *
762+ * @return A {@code Future} object representing the pending result
763+ *
764+ * @throws IllegalArgumentException
765+ * If the position is negative
766+ * @throws NonWritableChannelException
767+ * If this channel was not opened for writing
768+ */
769+ public abstract Future<Integer> write(ByteBuffer src, long position);
770+}
java/pkg/java/nio/channels/AsynchronousServerSocketChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousServerSocketChannel.java+300−0
@@ -0,0 +1,300 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.channels.spi.*;
29+import java.net.SocketOption;
30+import java.net.SocketAddress;
31+import java.util.concurrent.Future;
32+import java.io.IOException;
33+
34+/**
35+ * An asynchronous channel for stream-oriented listening sockets.
36+ *
37+ * <p> An asynchronous server-socket channel is created by invoking the
38+ * {@link #open open} method of this class.
39+ * A newly-created asynchronous server-socket channel is open but not yet bound.
40+ * It can be bound to a local address and configured to listen for connections
41+ * by invoking the {@link #bind(SocketAddress,int) bind} method. Once bound,
42+ * the {@link #accept(Object,CompletionHandler) accept} method
43+ * is used to initiate the accepting of connections to the channel's socket.
44+ * An attempt to invoke the <tt>accept</tt> method on an unbound channel will
45+ * cause a {@link NotYetBoundException} to be thrown.
46+ *
47+ * <p> Channels of this type are safe for use by multiple concurrent threads
48+ * though at most one accept operation can be outstanding at any time.
49+ * If a thread initiates an accept operation before a previous accept operation
50+ * has completed then an {@link AcceptPendingException} will be thrown.
51+ *
52+ * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
53+ * setOption} method. Channels of this type support the following options:
54+ * <blockquote>
55+ * <table border>
56+ * <tr>
57+ * <th>Option Name</th>
58+ * <th>Description</th>
59+ * </tr>
60+ * <tr>
61+ * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
62+ * <td> The size of the socket receive buffer </td>
63+ * </tr>
64+ * <tr>
65+ * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
66+ * <td> Re-use address </td>
67+ * </tr>
68+ * </table>
69+ * </blockquote>
70+ * Additional (implementation specific) options may also be supported.
71+ *
72+ * <p> <b>Usage Example:</b>
73+ * <pre>
74+ * final AsynchronousServerSocketChannel listener =
75+ * AsynchronousServerSocketChannel.open().bind(new InetSocketAddress(5000));
76+ *
77+ * listener.accept(null, new CompletionHandler&lt;AsynchronousSocketChannel,Void&gt;() {
78+ * public void completed(AsynchronousSocketChannel ch, Void att) {
79+ * // accept the next connection
80+ * listener.accept(null, this);
81+ *
82+ * // handle this connection
83+ * handle(ch);
84+ * }
85+ * public void failed(Throwable exc, Void att) {
86+ * ...
87+ * }
88+ * });
89+ * </pre>
90+ *
91+ * @since 1.7
92+ */
93+
94+public abstract class AsynchronousServerSocketChannel
95+ implements AsynchronousChannel, NetworkChannel
96+{
97+ private final AsynchronousChannelProvider provider;
98+
99+ /**
100+ * Initializes a new instance of this class.
101+ */
102+ protected AsynchronousServerSocketChannel(AsynchronousChannelProvider provider) {
103+ this.provider = provider;
104+ }
105+
106+ /**
107+ * Returns the provider that created this channel.
108+ */
109+ public final AsynchronousChannelProvider provider() {
110+ return provider;
111+ }
112+
113+ /**
114+ * Opens an asynchronous server-socket channel.
115+ *
116+ * <p> The new channel is created by invoking the {@link
117+ * java.nio.channels.spi.AsynchronousChannelProvider#openAsynchronousServerSocketChannel
118+ * openAsynchronousServerSocketChannel} method on the {@link
119+ * java.nio.channels.spi.AsynchronousChannelProvider} object that created
120+ * the given group. If the group parameter is <tt>null</tt> then the
121+ * resulting channel is created by the system-wide default provider, and
122+ * bound to the <em>default group</em>.
123+ *
124+ * @param group
125+ * The group to which the newly constructed channel should be bound,
126+ * or <tt>null</tt> for the default group
127+ *
128+ * @return A new asynchronous server socket channel
129+ *
130+ * @throws ShutdownChannelGroupException
131+ * If the channel group is shutdown
132+ * @throws IOException
133+ * If an I/O error occurs
134+ */
135+ public static AsynchronousServerSocketChannel open(AsynchronousChannelGroup group)
136+ throws IOException
137+ {
138+ AsynchronousChannelProvider provider = (group == null) ?
139+ AsynchronousChannelProvider.provider() : group.provider();
140+ return provider.openAsynchronousServerSocketChannel(group);
141+ }
142+
143+ /**
144+ * Opens an asynchronous server-socket channel.
145+ *
146+ * <p> This method returns an asynchronous server socket channel that is
147+ * bound to the <em>default group</em>. This method is equivalent to evaluating
148+ * the expression:
149+ * <blockquote><pre>
150+ * open((AsynchronousChannelGroup)null);
151+ * </pre></blockquote>
152+ *
153+ * @return A new asynchronous server socket channel
154+ *
155+ * @throws IOException
156+ * If an I/O error occurs
157+ */
158+ public static AsynchronousServerSocketChannel open()
159+ throws IOException
160+ {
161+ return open(null);
162+ }
163+
164+ /**
165+ * Binds the channel's socket to a local address and configures the socket to
166+ * listen for connections.
167+ *
168+ * <p> An invocation of this method is equivalent to the following:
169+ * <blockquote><pre>
170+ * bind(local, 0);
171+ * </pre></blockquote>
172+ *
173+ * @param local
174+ * The local address to bind the socket, or <tt>null</tt> to bind
175+ * to an automatically assigned socket address
176+ *
177+ * @return This channel
178+ *
179+ * @throws AlreadyBoundException {@inheritDoc}
180+ * @throws UnsupportedAddressTypeException {@inheritDoc}
181+ * @throws SecurityException {@inheritDoc}
182+ * @throws ClosedChannelException {@inheritDoc}
183+ * @throws IOException {@inheritDoc}
184+ */
185+ public final AsynchronousServerSocketChannel bind(SocketAddress local)
186+ throws IOException
187+ {
188+ return bind(local, 0);
189+ }
190+
191+ /**
192+ * Binds the channel's socket to a local address and configures the socket to
193+ * listen for connections.
194+ *
195+ * <p> This method is used to establish an association between the socket and
196+ * a local address. Once an association is established then the socket remains
197+ * bound until the associated channel is closed.
198+ *
199+ * <p> The {@code backlog} parameter is the maximum number of pending
200+ * connections on the socket. Its exact semantics are implementation specific.
201+ * In particular, an implementation may impose a maximum length or may choose
202+ * to ignore the parameter altogther. If the {@code backlog} parameter has
203+ * the value {@code 0}, or a negative value, then an implementation specific
204+ * default is used.
205+ *
206+ * @param local
207+ * The local address to bind the socket, or {@code null} to bind
208+ * to an automatically assigned socket address
209+ * @param backlog
210+ * The maximum number of pending connections
211+ *
212+ * @return This channel
213+ *
214+ * @throws AlreadyBoundException
215+ * If the socket is already bound
216+ * @throws UnsupportedAddressTypeException
217+ * If the type of the given address is not supported
218+ * @throws SecurityException
219+ * If a security manager has been installed and its {@link
220+ * SecurityManager#checkListen checkListen} method denies the operation
221+ * @throws ClosedChannelException
222+ * If the channel is closed
223+ * @throws IOException
224+ * If some other I/O error occurs
225+ */
226+ public abstract AsynchronousServerSocketChannel bind(SocketAddress local, int backlog)
227+ throws IOException;
228+
229+ /**
230+ * @throws IllegalArgumentException {@inheritDoc}
231+ * @throws ClosedChannelException {@inheritDoc}
232+ * @throws IOException {@inheritDoc}
233+ */
234+ public abstract <T> AsynchronousServerSocketChannel setOption(SocketOption<T> name, T value)
235+ throws IOException;
236+
237+ /**
238+ * Accepts a connection.
239+ *
240+ * <p> This method initiates an asynchronous operation to accept a
241+ * connection made to this channel's socket. The {@code handler} parameter is
242+ * a completion handler that is invoked when a connection is accepted (or
243+ * the operation fails). The result passed to the completion handler is
244+ * the {@link AsynchronousSocketChannel} to the new connection.
245+ *
246+ * <p> When a new connection is accepted then the resulting {@code
247+ * AsynchronousSocketChannel} will be bound to the same {@link
248+ * AsynchronousChannelGroup} as this channel. If the group is {@link
249+ * AsynchronousChannelGroup#isShutdown shutdown} and a connection is accepted,
250+ * then the connection is closed, and the operation completes with an {@code
251+ * IOException} and cause {@link ShutdownChannelGroupException}.
252+ *
253+ * <p> To allow for concurrent handling of new connections, the completion
254+ * handler is not invoked directly by the initiating thread when a new
255+ * connection is accepted immediately (see <a
256+ * href="AsynchronousChannelGroup.html#threading">Threading<a>).
257+ *
258+ * <p> If a security manager has been installed then it verifies that the
259+ * address and port number of the connection's remote endpoint are permitted
260+ * by the security manager's {@link SecurityManager#checkAccept checkAccept}
261+ * method. The permission check is performed with privileges that are restricted
262+ * by the calling context of this method. If the permission check fails then
263+ * the connection is closed and the operation completes with a {@link
264+ * SecurityException}.
265+ *
266+ * @param attachment
267+ * The object to attach to the I/O operation; can be {@code null}
268+ * @param handler
269+ * The handler for consuming the result
270+ *
271+ * @throws AcceptPendingException
272+ * If an accept operation is already in progress on this channel
273+ * @throws NotYetBoundException
274+ * If this channel's socket has not yet been bound
275+ * @throws ShutdownChannelGroupException
276+ * If the channel group has terminated
277+ */
278+ public abstract <A> void accept(A attachment,
279+ CompletionHandler<AsynchronousSocketChannel,? super A> handler);
280+
281+ /**
282+ * Accepts a connection.
283+ *
284+ * <p> This method initiates an asynchronous operation to accept a
285+ * connection made to this channel's socket. The method behaves in exactly
286+ * the same manner as the {@link #accept(Object, CompletionHandler)} method
287+ * except that instead of specifying a completion handler, this method
288+ * returns a {@code Future} representing the pending result. The {@code
289+ * Future}'s {@link Future#get() get} method returns the {@link
290+ * AsynchronousSocketChannel} to the new connection on successful completion.
291+ *
292+ * @return a {@code Future} object representing the pending result
293+ *
294+ * @throws AcceptPendingException
295+ * If an accept operation is already in progress on this channel
296+ * @throws NotYetBoundException
297+ * If this channel's socket has not yet been bound
298+ */
299+ public abstract Future<AsynchronousSocketChannel> accept();
300+}
java/pkg/java/nio/channels/AsynchronousSocketChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/AsynchronousSocketChannel.java+648−0
@@ -0,0 +1,648 @@
1+/*
2+ * Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.channels.spi.*;
29+import java.util.concurrent.TimeUnit;
30+import java.util.concurrent.Future;
31+import java.io.IOException;
32+import java.net.SocketOption;
33+import java.net.SocketAddress;
34+import java.nio.ByteBuffer;
35+
36+/**
37+ * An asynchronous channel for stream-oriented connecting sockets.
38+ *
39+ * <p> Asynchronous socket channels are created in one of two ways. A newly-created
40+ * {@code AsynchronousSocketChannel} is created by invoking one of the {@link
41+ * #open open} methods defined by this class. A newly-created channel is open but
42+ * not yet connected. A connected {@code AsynchronousSocketChannel} is created
43+ * when a connection is made to the socket of an {@link AsynchronousServerSocketChannel}.
44+ * It is not possible to create an asynchronous socket channel for an arbitrary,
45+ * pre-existing {@link java.net.Socket socket}.
46+ *
47+ * <p> A newly-created channel is connected by invoking its {@link #connect connect}
48+ * method; once connected, a channel remains connected until it is closed. Whether
49+ * or not a socket channel is connected may be determined by invoking its {@link
50+ * #getRemoteAddress getRemoteAddress} method. An attempt to invoke an I/O
51+ * operation upon an unconnected channel will cause a {@link NotYetConnectedException}
52+ * to be thrown.
53+ *
54+ * <p> Channels of this type are safe for use by multiple concurrent threads.
55+ * They support concurrent reading and writing, though at most one read operation
56+ * and one write operation can be outstanding at any time.
57+ * If a thread initiates a read operation before a previous read operation has
58+ * completed then a {@link ReadPendingException} will be thrown. Similarly, an
59+ * attempt to initiate a write operation before a previous write has completed
60+ * will throw a {@link WritePendingException}.
61+ *
62+ * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
63+ * setOption} method. Asynchronous socket channels support the following options:
64+ * <blockquote>
65+ * <table border>
66+ * <tr>
67+ * <th>Option Name</th>
68+ * <th>Description</th>
69+ * </tr>
70+ * <tr>
71+ * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td>
72+ * <td> The size of the socket send buffer </td>
73+ * </tr>
74+ * <tr>
75+ * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
76+ * <td> The size of the socket receive buffer </td>
77+ * </tr>
78+ * <tr>
79+ * <td> {@link java.net.StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} </td>
80+ * <td> Keep connection alive </td>
81+ * </tr>
82+ * <tr>
83+ * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
84+ * <td> Re-use address </td>
85+ * </tr>
86+ * <tr>
87+ * <td> {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY} </td>
88+ * <td> Disable the Nagle algorithm </td>
89+ * </tr>
90+ * </table>
91+ * </blockquote>
92+ * Additional (implementation specific) options may also be supported.
93+ *
94+ * <h4>Timeouts</h4>
95+ *
96+ * <p> The {@link #read(ByteBuffer,long,TimeUnit,Object,CompletionHandler) read}
97+ * and {@link #write(ByteBuffer,long,TimeUnit,Object,CompletionHandler) write}
98+ * methods defined by this class allow a timeout to be specified when initiating
99+ * a read or write operation. If the timeout elapses before an operation completes
100+ * then the operation completes with the exception {@link
101+ * InterruptedByTimeoutException}. A timeout may leave the channel, or the
102+ * underlying connection, in an inconsistent state. Where the implementation
103+ * cannot guarantee that bytes have not been read from the channel then it puts
104+ * the channel into an implementation specific <em>error state</em>. A subsequent
105+ * attempt to initiate a {@code read} operation causes an unspecified runtime
106+ * exception to be thrown. Similarly if a {@code write} operation times out and
107+ * the implementation cannot guarantee bytes have not been written to the
108+ * channel then further attempts to {@code write} to the channel cause an
109+ * unspecified runtime exception to be thrown. When a timeout elapses then the
110+ * state of the {@link ByteBuffer}, or the sequence of buffers, for the I/O
111+ * operation is not defined. Buffers should be discarded or at least care must
112+ * be taken to ensure that the buffers are not accessed while the channel remains
113+ * open. All methods that accept timeout parameters treat values less than or
114+ * equal to zero to mean that the I/O operation does not timeout.
115+ *
116+ * @since 1.7
117+ */
118+
119+public abstract class AsynchronousSocketChannel
120+ implements AsynchronousByteChannel, NetworkChannel
121+{
122+ private final AsynchronousChannelProvider provider;
123+
124+ /**
125+ * Initializes a new instance of this class.
126+ */
127+ protected AsynchronousSocketChannel(AsynchronousChannelProvider provider) {
128+ this.provider = provider;
129+ }
130+
131+ /**
132+ * Returns the provider that created this channel.
133+ */
134+ public final AsynchronousChannelProvider provider() {
135+ return provider;
136+ }
137+
138+ /**
139+ * Opens an asynchronous socket channel.
140+ *
141+ * <p> The new channel is created by invoking the {@link
142+ * AsynchronousChannelProvider#openAsynchronousSocketChannel
143+ * openAsynchronousSocketChannel} method on the {@link
144+ * AsynchronousChannelProvider} that created the group. If the group parameter
145+ * is {@code null} then the resulting channel is created by the system-wide
146+ * default provider, and bound to the <em>default group</em>.
147+ *
148+ * @param group
149+ * The group to which the newly constructed channel should be bound,
150+ * or {@code null} for the default group
151+ *
152+ * @return A new asynchronous socket channel
153+ *
154+ * @throws ShutdownChannelGroupException
155+ * If the channel group is shutdown
156+ * @throws IOException
157+ * If an I/O error occurs
158+ */
159+ public static AsynchronousSocketChannel open(AsynchronousChannelGroup group)
160+ throws IOException
161+ {
162+ AsynchronousChannelProvider provider = (group == null) ?
163+ AsynchronousChannelProvider.provider() : group.provider();
164+ return provider.openAsynchronousSocketChannel(group);
165+ }
166+
167+ /**
168+ * Opens an asynchronous socket channel.
169+ *
170+ * <p> This method returns an asynchronous socket channel that is bound to
171+ * the <em>default group</em>.This method is equivalent to evaluating the
172+ * expression:
173+ * <blockquote><pre>
174+ * open((AsynchronousChannelGroup)null);
175+ * </pre></blockquote>
176+ *
177+ * @return A new asynchronous socket channel
178+ *
179+ * @throws IOException
180+ * If an I/O error occurs
181+ */
182+ public static AsynchronousSocketChannel open()
183+ throws IOException
184+ {
185+ return open(null);
186+ }
187+
188+
189+ // -- socket options and related --
190+
191+ /**
192+ * @throws ConnectionPendingException
193+ * If a connection operation is already in progress on this channel
194+ * @throws AlreadyBoundException {@inheritDoc}
195+ * @throws UnsupportedAddressTypeException {@inheritDoc}
196+ * @throws ClosedChannelException {@inheritDoc}
197+ * @throws IOException {@inheritDoc}
198+ */
199+ @Override
200+ public abstract AsynchronousSocketChannel bind(SocketAddress local)
201+ throws IOException;
202+
203+ /**
204+ * @throws IllegalArgumentException {@inheritDoc}
205+ * @throws ClosedChannelException {@inheritDoc}
206+ * @throws IOException {@inheritDoc}
207+ */
208+ @Override
209+ public abstract <T> AsynchronousSocketChannel setOption(SocketOption<T> name, T value)
210+ throws IOException;
211+
212+ /**
213+ * Shutdown the connection for reading without closing the channel.
214+ *
215+ * <p> Once shutdown for reading then further reads on the channel will
216+ * return {@code -1}, the end-of-stream indication. If the input side of the
217+ * connection is already shutdown then invoking this method has no effect.
218+ * The effect on an outstanding read operation is system dependent and
219+ * therefore not specified. The effect, if any, when there is data in the
220+ * socket receive buffer that has not been read, or data arrives subsequently,
221+ * is also system dependent.
222+ *
223+ * @return The channel
224+ *
225+ * @throws NotYetConnectedException
226+ * If this channel is not yet connected
227+ * @throws ClosedChannelException
228+ * If this channel is closed
229+ * @throws IOException
230+ * If some other I/O error occurs
231+ */
232+ public abstract AsynchronousSocketChannel shutdownInput() throws IOException;
233+
234+ /**
235+ * Shutdown the connection for writing without closing the channel.
236+ *
237+ * <p> Once shutdown for writing then further attempts to write to the
238+ * channel will throw {@link ClosedChannelException}. If the output side of
239+ * the connection is already shutdown then invoking this method has no
240+ * effect. The effect on an outstanding write operation is system dependent
241+ * and therefore not specified.
242+ *
243+ * @return The channel
244+ *
245+ * @throws NotYetConnectedException
246+ * If this channel is not yet connected
247+ * @throws ClosedChannelException
248+ * If this channel is closed
249+ * @throws IOException
250+ * If some other I/O error occurs
251+ */
252+ public abstract AsynchronousSocketChannel shutdownOutput() throws IOException;
253+
254+ // -- state --
255+
256+ /**
257+ * Returns the remote address to which this channel's socket is connected.
258+ *
259+ * <p> Where the channel is bound and connected to an Internet Protocol
260+ * socket address then the return value from this method is of type {@link
261+ * java.net.InetSocketAddress}.
262+ *
263+ * @return The remote address; {@code null} if the channel's socket is not
264+ * connected
265+ *
266+ * @throws ClosedChannelException
267+ * If the channel is closed
268+ * @throws IOException
269+ * If an I/O error occurs
270+ */
271+ public abstract SocketAddress getRemoteAddress() throws IOException;
272+
273+ // -- asynchronous operations --
274+
275+ /**
276+ * Connects this channel.
277+ *
278+ * <p> This method initiates an operation to connect this channel. The
279+ * {@code handler} parameter is a completion handler that is invoked when
280+ * the connection is successfully established or connection cannot be
281+ * established. If the connection cannot be established then the channel is
282+ * closed.
283+ *
284+ * <p> This method performs exactly the same security checks as the {@link
285+ * java.net.Socket} class. That is, if a security manager has been
286+ * installed then this method verifies that its {@link
287+ * java.lang.SecurityManager#checkConnect checkConnect} method permits
288+ * connecting to the address and port number of the given remote endpoint.
289+ *
290+ * @param remote
291+ * The remote address to which this channel is to be connected
292+ * @param attachment
293+ * The object to attach to the I/O operation; can be {@code null}
294+ * @param handler
295+ * The handler for consuming the result
296+ *
297+ * @throws UnresolvedAddressException
298+ * If the given remote address is not fully resolved
299+ * @throws UnsupportedAddressTypeException
300+ * If the type of the given remote address is not supported
301+ * @throws AlreadyConnectedException
302+ * If this channel is already connected
303+ * @throws ConnectionPendingException
304+ * If a connection operation is already in progress on this channel
305+ * @throws ShutdownChannelGroupException
306+ * If the channel group has terminated
307+ * @throws SecurityException
308+ * If a security manager has been installed
309+ * and it does not permit access to the given remote endpoint
310+ *
311+ * @see #getRemoteAddress
312+ */
313+ public abstract <A> void connect(SocketAddress remote,
314+ A attachment,
315+ CompletionHandler<Void,? super A> handler);
316+
317+ /**
318+ * Connects this channel.
319+ *
320+ * <p> This method initiates an operation to connect this channel. This
321+ * method behaves in exactly the same manner as the {@link
322+ * #connect(SocketAddress, Object, CompletionHandler)} method except that
323+ * instead of specifying a completion handler, this method returns a {@code
324+ * Future} representing the pending result. The {@code Future}'s {@link
325+ * Future#get() get} method returns {@code null} on successful completion.
326+ *
327+ * @param remote
328+ * The remote address to which this channel is to be connected
329+ *
330+ * @return A {@code Future} object representing the pending result
331+ *
332+ * @throws UnresolvedAddressException
333+ * If the given remote address is not fully resolved
334+ * @throws UnsupportedAddressTypeException
335+ * If the type of the given remote address is not supported
336+ * @throws AlreadyConnectedException
337+ * If this channel is already connected
338+ * @throws ConnectionPendingException
339+ * If a connection operation is already in progress on this channel
340+ * @throws SecurityException
341+ * If a security manager has been installed
342+ * and it does not permit access to the given remote endpoint
343+ */
344+ public abstract Future<Void> connect(SocketAddress remote);
345+
346+ /**
347+ * Reads a sequence of bytes from this channel into the given buffer.
348+ *
349+ * <p> This method initiates an asynchronous read operation to read a
350+ * sequence of bytes from this channel into the given buffer. The {@code
351+ * handler} parameter is a completion handler that is invoked when the read
352+ * operation completes (or fails). The result passed to the completion
353+ * handler is the number of bytes read or {@code -1} if no bytes could be
354+ * read because the channel has reached end-of-stream.
355+ *
356+ * <p> If a timeout is specified and the timeout elapses before the operation
357+ * completes then the operation completes with the exception {@link
358+ * InterruptedByTimeoutException}. Where a timeout occurs, and the
359+ * implementation cannot guarantee that bytes have not been read, or will not
360+ * be read from the channel into the given buffer, then further attempts to
361+ * read from the channel will cause an unspecific runtime exception to be
362+ * thrown.
363+ *
364+ * <p> Otherwise this method works in the same manner as the {@link
365+ * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}
366+ * method.
367+ *
368+ * @param dst
369+ * The buffer into which bytes are to be transferred
370+ * @param timeout
371+ * The maximum time for the I/O operation to complete
372+ * @param unit
373+ * The time unit of the {@code timeout} argument
374+ * @param attachment
375+ * The object to attach to the I/O operation; can be {@code null}
376+ * @param handler
377+ * The handler for consuming the result
378+ *
379+ * @throws IllegalArgumentException
380+ * If the buffer is read-only
381+ * @throws ReadPendingException
382+ * If a read operation is already in progress on this channel
383+ * @throws NotYetConnectedException
384+ * If this channel is not yet connected
385+ * @throws ShutdownChannelGroupException
386+ * If the channel group has terminated
387+ */
388+ public abstract <A> void read(ByteBuffer dst,
389+ long timeout,
390+ TimeUnit unit,
391+ A attachment,
392+ CompletionHandler<Integer,? super A> handler);
393+
394+ /**
395+ * @throws IllegalArgumentException {@inheritDoc}
396+ * @throws ReadPendingException {@inheritDoc}
397+ * @throws NotYetConnectedException
398+ * If this channel is not yet connected
399+ * @throws ShutdownChannelGroupException
400+ * If the channel group has terminated
401+ */
402+ @Override
403+ public final <A> void read(ByteBuffer dst,
404+ A attachment,
405+ CompletionHandler<Integer,? super A> handler)
406+ {
407+ read(dst, 0L, TimeUnit.MILLISECONDS, attachment, handler);
408+ }
409+
410+ /**
411+ * @throws IllegalArgumentException {@inheritDoc}
412+ * @throws ReadPendingException {@inheritDoc}
413+ * @throws NotYetConnectedException
414+ * If this channel is not yet connected
415+ */
416+ @Override
417+ public abstract Future<Integer> read(ByteBuffer dst);
418+
419+ /**
420+ * Reads a sequence of bytes from this channel into a subsequence of the
421+ * given buffers. This operation, sometimes called a <em>scattering read</em>,
422+ * is often useful when implementing network protocols that group data into
423+ * segments consisting of one or more fixed-length headers followed by a
424+ * variable-length body. The {@code handler} parameter is a completion
425+ * handler that is invoked when the read operation completes (or fails). The
426+ * result passed to the completion handler is the number of bytes read or
427+ * {@code -1} if no bytes could be read because the channel has reached
428+ * end-of-stream.
429+ *
430+ * <p> This method initiates a read of up to <i>r</i> bytes from this channel,
431+ * where <i>r</i> is the total number of bytes remaining in the specified
432+ * subsequence of the given buffer array, that is,
433+ *
434+ * <blockquote><pre>
435+ * dsts[offset].remaining()
436+ * + dsts[offset+1].remaining()
437+ * + ... + dsts[offset+length-1].remaining()</pre></blockquote>
438+ *
439+ * at the moment that the read is attempted.
440+ *
441+ * <p> Suppose that a byte sequence of length <i>n</i> is read, where
442+ * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
443+ * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
444+ * are transferred into buffer <tt>dsts[offset]</tt>, up to the next
445+ * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
446+ * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence
447+ * is transferred into the given buffers. As many bytes as possible are
448+ * transferred into each buffer, hence the final position of each updated
449+ * buffer, except the last updated buffer, is guaranteed to be equal to
450+ * that buffer's limit. The underlying operating system may impose a limit
451+ * on the number of buffers that may be used in an I/O operation. Where the
452+ * number of buffers (with bytes remaining), exceeds this limit, then the
453+ * I/O operation is performed with the maximum number of buffers allowed by
454+ * the operating system.
455+ *
456+ * <p> If a timeout is specified and the timeout elapses before the operation
457+ * completes then it completes with the exception {@link
458+ * InterruptedByTimeoutException}. Where a timeout occurs, and the
459+ * implementation cannot guarantee that bytes have not been read, or will not
460+ * be read from the channel into the given buffers, then further attempts to
461+ * read from the channel will cause an unspecific runtime exception to be
462+ * thrown.
463+ *
464+ * @param dsts
465+ * The buffers into which bytes are to be transferred
466+ * @param offset
467+ * The offset within the buffer array of the first buffer into which
468+ * bytes are to be transferred; must be non-negative and no larger than
469+ * {@code dsts.length}
470+ * @param length
471+ * The maximum number of buffers to be accessed; must be non-negative
472+ * and no larger than {@code dsts.length - offset}
473+ * @param timeout
474+ * The maximum time for the I/O operation to complete
475+ * @param unit
476+ * The time unit of the {@code timeout} argument
477+ * @param attachment
478+ * The object to attach to the I/O operation; can be {@code null}
479+ * @param handler
480+ * The handler for consuming the result
481+ *
482+ * @throws IndexOutOfBoundsException
483+ * If the pre-conditions for the {@code offset} and {@code length}
484+ * parameter aren't met
485+ * @throws IllegalArgumentException
486+ * If the buffer is read-only
487+ * @throws ReadPendingException
488+ * If a read operation is already in progress on this channel
489+ * @throws NotYetConnectedException
490+ * If this channel is not yet connected
491+ * @throws ShutdownChannelGroupException
492+ * If the channel group has terminated
493+ */
494+ public abstract <A> void read(ByteBuffer[] dsts,
495+ int offset,
496+ int length,
497+ long timeout,
498+ TimeUnit unit,
499+ A attachment,
500+ CompletionHandler<Long,? super A> handler);
501+
502+ /**
503+ * Writes a sequence of bytes to this channel from the given buffer.
504+ *
505+ * <p> This method initiates an asynchronous write operation to write a
506+ * sequence of bytes to this channel from the given buffer. The {@code
507+ * handler} parameter is a completion handler that is invoked when the write
508+ * operation completes (or fails). The result passed to the completion
509+ * handler is the number of bytes written.
510+ *
511+ * <p> If a timeout is specified and the timeout elapses before the operation
512+ * completes then it completes with the exception {@link
513+ * InterruptedByTimeoutException}. Where a timeout occurs, and the
514+ * implementation cannot guarantee that bytes have not been written, or will
515+ * not be written to the channel from the given buffer, then further attempts
516+ * to write to the channel will cause an unspecific runtime exception to be
517+ * thrown.
518+ *
519+ * <p> Otherwise this method works in the same manner as the {@link
520+ * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}
521+ * method.
522+ *
523+ * @param src
524+ * The buffer from which bytes are to be retrieved
525+ * @param timeout
526+ * The maximum time for the I/O operation to complete
527+ * @param unit
528+ * The time unit of the {@code timeout} argument
529+ * @param attachment
530+ * The object to attach to the I/O operation; can be {@code null}
531+ * @param handler
532+ * The handler for consuming the result
533+ *
534+ * @throws WritePendingException
535+ * If a write operation is already in progress on this channel
536+ * @throws NotYetConnectedException
537+ * If this channel is not yet connected
538+ * @throws ShutdownChannelGroupException
539+ * If the channel group has terminated
540+ */
541+ public abstract <A> void write(ByteBuffer src,
542+ long timeout,
543+ TimeUnit unit,
544+ A attachment,
545+ CompletionHandler<Integer,? super A> handler);
546+
547+ /**
548+ * @throws WritePendingException {@inheritDoc}
549+ * @throws NotYetConnectedException
550+ * If this channel is not yet connected
551+ * @throws ShutdownChannelGroupException
552+ * If the channel group has terminated
553+ */
554+ @Override
555+ public final <A> void write(ByteBuffer src,
556+ A attachment,
557+ CompletionHandler<Integer,? super A> handler)
558+
559+ {
560+ write(src, 0L, TimeUnit.MILLISECONDS, attachment, handler);
561+ }
562+
563+ /**
564+ * @throws WritePendingException {@inheritDoc}
565+ * @throws NotYetConnectedException
566+ * If this channel is not yet connected
567+ */
568+ @Override
569+ public abstract Future<Integer> write(ByteBuffer src);
570+
571+ /**
572+ * Writes a sequence of bytes to this channel from a subsequence of the given
573+ * buffers. This operation, sometimes called a <em>gathering write</em>, is
574+ * often useful when implementing network protocols that group data into
575+ * segments consisting of one or more fixed-length headers followed by a
576+ * variable-length body. The {@code handler} parameter is a completion
577+ * handler that is invoked when the write operation completes (or fails).
578+ * The result passed to the completion handler is the number of bytes written.
579+ *
580+ * <p> This method initiates a write of up to <i>r</i> bytes to this channel,
581+ * where <i>r</i> is the total number of bytes remaining in the specified
582+ * subsequence of the given buffer array, that is,
583+ *
584+ * <blockquote><pre>
585+ * srcs[offset].remaining()
586+ * + srcs[offset+1].remaining()
587+ * + ... + srcs[offset+length-1].remaining()</pre></blockquote>
588+ *
589+ * at the moment that the write is attempted.
590+ *
591+ * <p> Suppose that a byte sequence of length <i>n</i> is written, where
592+ * <tt>0</tt>&nbsp;<tt>&lt;</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
593+ * Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence
594+ * are written from buffer <tt>srcs[offset]</tt>, up to the next
595+ * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer
596+ * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is
597+ * written. As many bytes as possible are written from each buffer, hence
598+ * the final position of each updated buffer, except the last updated
599+ * buffer, is guaranteed to be equal to that buffer's limit. The underlying
600+ * operating system may impose a limit on the number of buffers that may be
601+ * used in an I/O operation. Where the number of buffers (with bytes
602+ * remaining), exceeds this limit, then the I/O operation is performed with
603+ * the maximum number of buffers allowed by the operating system.
604+ *
605+ * <p> If a timeout is specified and the timeout elapses before the operation
606+ * completes then it completes with the exception {@link
607+ * InterruptedByTimeoutException}. Where a timeout occurs, and the
608+ * implementation cannot guarantee that bytes have not been written, or will
609+ * not be written to the channel from the given buffers, then further attempts
610+ * to write to the channel will cause an unspecific runtime exception to be
611+ * thrown.
612+ *
613+ * @param srcs
614+ * The buffers from which bytes are to be retrieved
615+ * @param offset
616+ * The offset within the buffer array of the first buffer from which
617+ * bytes are to be retrieved; must be non-negative and no larger
618+ * than {@code srcs.length}
619+ * @param length
620+ * The maximum number of buffers to be accessed; must be non-negative
621+ * and no larger than {@code srcs.length - offset}
622+ * @param timeout
623+ * The maximum time for the I/O operation to complete
624+ * @param unit
625+ * The time unit of the {@code timeout} argument
626+ * @param attachment
627+ * The object to attach to the I/O operation; can be {@code null}
628+ * @param handler
629+ * The handler for consuming the result
630+ *
631+ * @throws IndexOutOfBoundsException
632+ * If the pre-conditions for the {@code offset} and {@code length}
633+ * parameter aren't met
634+ * @throws WritePendingException
635+ * If a write operation is already in progress on this channel
636+ * @throws NotYetConnectedException
637+ * If this channel is not yet connected
638+ * @throws ShutdownChannelGroupException
639+ * If the channel group has terminated
640+ */
641+ public abstract <A> void write(ByteBuffer[] srcs,
642+ int offset,
643+ int length,
644+ long timeout,
645+ TimeUnit unit,
646+ A attachment,
647+ CompletionHandler<Long,? super A> handler);
648+}
java/pkg/java/nio/channels/ByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/ByteChannel.java+45−0
@@ -0,0 +1,45 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+
30+
31+/**
32+ * A channel that can read and write bytes. This interface simply unifies
33+ * {@link ReadableByteChannel} and {@link WritableByteChannel}; it does not
34+ * specify any new operations.
35+ *
36+ * @author Mark Reinhold
37+ * @author JSR-51 Expert Group
38+ * @since 1.4
39+ */
40+
41+public interface ByteChannel
42+ extends ReadableByteChannel, WritableByteChannel
43+{
44+
45+}
java/pkg/java/nio/channels/Channel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channel.java+84−0
@@ -0,0 +1,84 @@
1+/*
2+ * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.io.Closeable;
30+
31+
32+/**
33+ * A nexus for I/O operations.
34+ *
35+ * <p> A channel represents an open connection to an entity such as a hardware
36+ * device, a file, a network socket, or a program component that is capable of
37+ * performing one or more distinct I/O operations, for example reading or
38+ * writing.
39+ *
40+ * <p> A channel is either open or closed. A channel is open upon creation,
41+ * and once closed it remains closed. Once a channel is closed, any attempt to
42+ * invoke an I/O operation upon it will cause a {@link ClosedChannelException}
43+ * to be thrown. Whether or not a channel is open may be tested by invoking
44+ * its {@link #isOpen isOpen} method.
45+ *
46+ * <p> Channels are, in general, intended to be safe for multithreaded access
47+ * as described in the specifications of the interfaces and classes that extend
48+ * and implement this interface.
49+ *
50+ *
51+ * @author Mark Reinhold
52+ * @author JSR-51 Expert Group
53+ * @since 1.4
54+ */
55+
56+public interface Channel extends Closeable {
57+
58+ /**
59+ * Tells whether or not this channel is open. </p>
60+ *
61+ * @return <tt>true</tt> if, and only if, this channel is open
62+ */
63+ public boolean isOpen();
64+
65+ /**
66+ * Closes this channel.
67+ *
68+ * <p> After a channel is closed, any further attempt to invoke I/O
69+ * operations upon it will cause a {@link ClosedChannelException} to be
70+ * thrown.
71+ *
72+ * <p> If this channel is already closed then invoking this method has no
73+ * effect.
74+ *
75+ * <p> This method may be invoked at any time. If some other thread has
76+ * already invoked it, however, then another invocation will block until
77+ * the first invocation is complete, after which it will return without
78+ * effect. </p>
79+ *
80+ * @throws IOException If an I/O error occurs
81+ */
82+ public void close() throws IOException;
83+
84+}
java/pkg/java/nio/channels/Channels$1.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels$2.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels$3.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels$ReadableByteChannelImpl.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels$WritableByteChannelImpl.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Channels.java+615−0
@@ -0,0 +1,615 @@
1+/*
2+ * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.FileInputStream;
29+import java.io.FileOutputStream;
30+import java.io.InputStream;
31+import java.io.OutputStream;
32+import java.io.Reader;
33+import java.io.Writer;
34+import java.io.IOException;
35+import java.nio.ByteBuffer;
36+import java.nio.charset.Charset;
37+import java.nio.charset.CharsetDecoder;
38+import java.nio.charset.CharsetEncoder;
39+import java.nio.charset.UnsupportedCharsetException;
40+import java.nio.channels.spi.AbstractInterruptibleChannel;
41+import java.util.concurrent.ExecutionException;
42+import sun.nio.ch.ChannelInputStream;
43+import sun.nio.cs.StreamDecoder;
44+import sun.nio.cs.StreamEncoder;
45+
46+
47+/**
48+ * Utility methods for channels and streams.
49+ *
50+ * <p> This class defines static methods that support the interoperation of the
51+ * stream classes of the <tt>{@link java.io}</tt> package with the channel
52+ * classes of this package. </p>
53+ *
54+ *
55+ * @author Mark Reinhold
56+ * @author Mike McCloskey
57+ * @author JSR-51 Expert Group
58+ * @since 1.4
59+ */
60+
61+public final class Channels {
62+
63+ private Channels() { } // No instantiation
64+
65+ private static void checkNotNull(Object o, String name) {
66+ if (o == null)
67+ throw new NullPointerException("\"" + name + "\" is null!");
68+ }
69+
70+ /**
71+ * Write all remaining bytes in buffer to the given channel.
72+ * If the channel is selectable then it must be configured blocking.
73+ */
74+ private static void writeFullyImpl(WritableByteChannel ch, ByteBuffer bb)
75+ throws IOException
76+ {
77+ while (bb.remaining() > 0) {
78+ int n = ch.write(bb);
79+ if (n <= 0)
80+ throw new RuntimeException("no bytes written");
81+ }
82+ }
83+
84+ /**
85+ * Write all remaining bytes in buffer to the given channel.
86+ *
87+ * @throws IllegalBlockingException
88+ * If the channel is selectable and configured non-blocking.
89+ */
90+ private static void writeFully(WritableByteChannel ch, ByteBuffer bb)
91+ throws IOException
92+ {
93+ if (ch instanceof SelectableChannel) {
94+ SelectableChannel sc = (SelectableChannel)ch;
95+ synchronized (sc.blockingLock()) {
96+ if (!sc.isBlocking())
97+ throw new IllegalBlockingModeException();
98+ writeFullyImpl(ch, bb);
99+ }
100+ } else {
101+ writeFullyImpl(ch, bb);
102+ }
103+ }
104+
105+ // -- Byte streams from channels --
106+
107+ /**
108+ * Constructs a stream that reads bytes from the given channel.
109+ *
110+ * <p> The <tt>read</tt> methods of the resulting stream will throw an
111+ * {@link IllegalBlockingModeException} if invoked while the underlying
112+ * channel is in non-blocking mode. The stream will not be buffered, and
113+ * it will not support the {@link InputStream#mark mark} or {@link
114+ * InputStream#reset reset} methods. The stream will be safe for access by
115+ * multiple concurrent threads. Closing the stream will in turn cause the
116+ * channel to be closed. </p>
117+ *
118+ * @param ch
119+ * The channel from which bytes will be read
120+ *
121+ * @return A new input stream
122+ */
123+ public static InputStream newInputStream(ReadableByteChannel ch) {
124+ checkNotNull(ch, "ch");
125+ return new sun.nio.ch.ChannelInputStream(ch);
126+ }
127+
128+ /**
129+ * Constructs a stream that writes bytes to the given channel.
130+ *
131+ * <p> The <tt>write</tt> methods of the resulting stream will throw an
132+ * {@link IllegalBlockingModeException} if invoked while the underlying
133+ * channel is in non-blocking mode. The stream will not be buffered. The
134+ * stream will be safe for access by multiple concurrent threads. Closing
135+ * the stream will in turn cause the channel to be closed. </p>
136+ *
137+ * @param ch
138+ * The channel to which bytes will be written
139+ *
140+ * @return A new output stream
141+ */
142+ public static OutputStream newOutputStream(final WritableByteChannel ch) {
143+ checkNotNull(ch, "ch");
144+
145+ return new OutputStream() {
146+
147+ private ByteBuffer bb = null;
148+ private byte[] bs = null; // Invoker's previous array
149+ private byte[] b1 = null;
150+
151+ public synchronized void write(int b) throws IOException {
152+ if (b1 == null)
153+ b1 = new byte[1];
154+ b1[0] = (byte)b;
155+ this.write(b1);
156+ }
157+
158+ public synchronized void write(byte[] bs, int off, int len)
159+ throws IOException
160+ {
161+ if ((off < 0) || (off > bs.length) || (len < 0) ||
162+ ((off + len) > bs.length) || ((off + len) < 0)) {
163+ throw new IndexOutOfBoundsException();
164+ } else if (len == 0) {
165+ return;
166+ }
167+ ByteBuffer bb = ((this.bs == bs)
168+ ? this.bb
169+ : ByteBuffer.wrap(bs));
170+ bb.limit(Math.min(off + len, bb.capacity()));
171+ bb.position(off);
172+ this.bb = bb;
173+ this.bs = bs;
174+ Channels.writeFully(ch, bb);
175+ }
176+
177+ public void close() throws IOException {
178+ ch.close();
179+ }
180+
181+ };
182+ }
183+
184+ /**
185+ * Constructs a stream that reads bytes from the given channel.
186+ *
187+ * <p> The stream will not be buffered, and it will not support the {@link
188+ * InputStream#mark mark} or {@link InputStream#reset reset} methods. The
189+ * stream will be safe for access by multiple concurrent threads. Closing
190+ * the stream will in turn cause the channel to be closed. </p>
191+ *
192+ * @param ch
193+ * The channel from which bytes will be read
194+ *
195+ * @return A new input stream
196+ *
197+ * @since 1.7
198+ */
199+ public static InputStream newInputStream(final AsynchronousByteChannel ch) {
200+ checkNotNull(ch, "ch");
201+ return new InputStream() {
202+
203+ private ByteBuffer bb = null;
204+ private byte[] bs = null; // Invoker's previous array
205+ private byte[] b1 = null;
206+
207+ @Override
208+ public synchronized int read() throws IOException {
209+ if (b1 == null)
210+ b1 = new byte[1];
211+ int n = this.read(b1);
212+ if (n == 1)
213+ return b1[0] & 0xff;
214+ return -1;
215+ }
216+
217+ @Override
218+ public synchronized int read(byte[] bs, int off, int len)
219+ throws IOException
220+ {
221+ if ((off < 0) || (off > bs.length) || (len < 0) ||
222+ ((off + len) > bs.length) || ((off + len) < 0)) {
223+ throw new IndexOutOfBoundsException();
224+ } else if (len == 0)
225+ return 0;
226+
227+ ByteBuffer bb = ((this.bs == bs)
228+ ? this.bb
229+ : ByteBuffer.wrap(bs));
230+ bb.position(off);
231+ bb.limit(Math.min(off + len, bb.capacity()));
232+ this.bb = bb;
233+ this.bs = bs;
234+
235+ boolean interrupted = false;
236+ try {
237+ for (;;) {
238+ try {
239+ return ch.read(bb).get();
240+ } catch (ExecutionException ee) {
241+ throw new IOException(ee.getCause());
242+ } catch (InterruptedException ie) {
243+ interrupted = true;
244+ }
245+ }
246+ } finally {
247+ if (interrupted)
248+ Thread.currentThread().interrupt();
249+ }
250+ }
251+
252+ @Override
253+ public void close() throws IOException {
254+ ch.close();
255+ }
256+ };
257+ }
258+
259+ /**
260+ * Constructs a stream that writes bytes to the given channel.
261+ *
262+ * <p> The stream will not be buffered. The stream will be safe for access
263+ * by multiple concurrent threads. Closing the stream will in turn cause
264+ * the channel to be closed. </p>
265+ *
266+ * @param ch
267+ * The channel to which bytes will be written
268+ *
269+ * @return A new output stream
270+ *
271+ * @since 1.7
272+ */
273+ public static OutputStream newOutputStream(final AsynchronousByteChannel ch) {
274+ checkNotNull(ch, "ch");
275+ return new OutputStream() {
276+
277+ private ByteBuffer bb = null;
278+ private byte[] bs = null; // Invoker's previous array
279+ private byte[] b1 = null;
280+
281+ @Override
282+ public synchronized void write(int b) throws IOException {
283+ if (b1 == null)
284+ b1 = new byte[1];
285+ b1[0] = (byte)b;
286+ this.write(b1);
287+ }
288+
289+ @Override
290+ public synchronized void write(byte[] bs, int off, int len)
291+ throws IOException
292+ {
293+ if ((off < 0) || (off > bs.length) || (len < 0) ||
294+ ((off + len) > bs.length) || ((off + len) < 0)) {
295+ throw new IndexOutOfBoundsException();
296+ } else if (len == 0) {
297+ return;
298+ }
299+ ByteBuffer bb = ((this.bs == bs)
300+ ? this.bb
301+ : ByteBuffer.wrap(bs));
302+ bb.limit(Math.min(off + len, bb.capacity()));
303+ bb.position(off);
304+ this.bb = bb;
305+ this.bs = bs;
306+
307+ boolean interrupted = false;
308+ try {
309+ while (bb.remaining() > 0) {
310+ try {
311+ ch.write(bb).get();
312+ } catch (ExecutionException ee) {
313+ throw new IOException(ee.getCause());
314+ } catch (InterruptedException ie) {
315+ interrupted = true;
316+ }
317+ }
318+ } finally {
319+ if (interrupted)
320+ Thread.currentThread().interrupt();
321+ }
322+ }
323+
324+ @Override
325+ public void close() throws IOException {
326+ ch.close();
327+ }
328+ };
329+ }
330+
331+
332+ // -- Channels from streams --
333+
334+ /**
335+ * Constructs a channel that reads bytes from the given stream.
336+ *
337+ * <p> The resulting channel will not be buffered; it will simply redirect
338+ * its I/O operations to the given stream. Closing the channel will in
339+ * turn cause the stream to be closed. </p>
340+ *
341+ * @param in
342+ * The stream from which bytes are to be read
343+ *
344+ * @return A new readable byte channel
345+ */
346+ public static ReadableByteChannel newChannel(final InputStream in) {
347+ checkNotNull(in, "in");
348+
349+ if (in instanceof FileInputStream &&
350+ FileInputStream.class.equals(in.getClass())) {
351+ return ((FileInputStream)in).getChannel();
352+ }
353+
354+ return new ReadableByteChannelImpl(in);
355+ }
356+
357+ private static class ReadableByteChannelImpl
358+ extends AbstractInterruptibleChannel // Not really interruptible
359+ implements ReadableByteChannel
360+ {
361+ InputStream in;
362+ private static final int TRANSFER_SIZE = 8192;
363+ private byte buf[] = new byte[0];
364+ private boolean open = true;
365+ private Object readLock = new Object();
366+
367+ ReadableByteChannelImpl(InputStream in) {
368+ this.in = in;
369+ }
370+
371+ public int read(ByteBuffer dst) throws IOException {
372+ int len = dst.remaining();
373+ int totalRead = 0;
374+ int bytesRead = 0;
375+ synchronized (readLock) {
376+ while (totalRead < len) {
377+ int bytesToRead = Math.min((len - totalRead),
378+ TRANSFER_SIZE);
379+ if (buf.length < bytesToRead)
380+ buf = new byte[bytesToRead];
381+ if ((totalRead > 0) && !(in.available() > 0))
382+ break; // block at most once
383+ try {
384+ begin();
385+ bytesRead = in.read(buf, 0, bytesToRead);
386+ } finally {
387+ end(bytesRead > 0);
388+ }
389+ if (bytesRead < 0)
390+ break;
391+ else
392+ totalRead += bytesRead;
393+ dst.put(buf, 0, bytesRead);
394+ }
395+ if ((bytesRead < 0) && (totalRead == 0))
396+ return -1;
397+
398+ return totalRead;
399+ }
400+ }
401+
402+ protected void implCloseChannel() throws IOException {
403+ in.close();
404+ open = false;
405+ }
406+ }
407+
408+
409+ /**
410+ * Constructs a channel that writes bytes to the given stream.
411+ *
412+ * <p> The resulting channel will not be buffered; it will simply redirect
413+ * its I/O operations to the given stream. Closing the channel will in
414+ * turn cause the stream to be closed. </p>
415+ *
416+ * @param out
417+ * The stream to which bytes are to be written
418+ *
419+ * @return A new writable byte channel
420+ */
421+ public static WritableByteChannel newChannel(final OutputStream out) {
422+ checkNotNull(out, "out");
423+
424+ if (out instanceof FileOutputStream &&
425+ FileOutputStream.class.equals(out.getClass())) {
426+ return ((FileOutputStream)out).getChannel();
427+ }
428+
429+ return new WritableByteChannelImpl(out);
430+ }
431+
432+ private static class WritableByteChannelImpl
433+ extends AbstractInterruptibleChannel // Not really interruptible
434+ implements WritableByteChannel
435+ {
436+ OutputStream out;
437+ private static final int TRANSFER_SIZE = 8192;
438+ private byte buf[] = new byte[0];
439+ private boolean open = true;
440+ private Object writeLock = new Object();
441+
442+ WritableByteChannelImpl(OutputStream out) {
443+ this.out = out;
444+ }
445+
446+ public int write(ByteBuffer src) throws IOException {
447+ int len = src.remaining();
448+ int totalWritten = 0;
449+ synchronized (writeLock) {
450+ while (totalWritten < len) {
451+ int bytesToWrite = Math.min((len - totalWritten),
452+ TRANSFER_SIZE);
453+ if (buf.length < bytesToWrite)
454+ buf = new byte[bytesToWrite];
455+ src.get(buf, 0, bytesToWrite);
456+ try {
457+ begin();
458+ out.write(buf, 0, bytesToWrite);
459+ } finally {
460+ end(bytesToWrite > 0);
461+ }
462+ totalWritten += bytesToWrite;
463+ }
464+ return totalWritten;
465+ }
466+ }
467+
468+ protected void implCloseChannel() throws IOException {
469+ out.close();
470+ open = false;
471+ }
472+ }
473+
474+
475+ // -- Character streams from channels --
476+
477+ /**
478+ * Constructs a reader that decodes bytes from the given channel using the
479+ * given decoder.
480+ *
481+ * <p> The resulting stream will contain an internal input buffer of at
482+ * least <tt>minBufferCap</tt> bytes. The stream's <tt>read</tt> methods
483+ * will, as needed, fill the buffer by reading bytes from the underlying
484+ * channel; if the channel is in non-blocking mode when bytes are to be
485+ * read then an {@link IllegalBlockingModeException} will be thrown. The
486+ * resulting stream will not otherwise be buffered, and it will not support
487+ * the {@link Reader#mark mark} or {@link Reader#reset reset} methods.
488+ * Closing the stream will in turn cause the channel to be closed. </p>
489+ *
490+ * @param ch
491+ * The channel from which bytes will be read
492+ *
493+ * @param dec
494+ * The charset decoder to be used
495+ *
496+ * @param minBufferCap
497+ * The minimum capacity of the internal byte buffer,
498+ * or <tt>-1</tt> if an implementation-dependent
499+ * default capacity is to be used
500+ *
501+ * @return A new reader
502+ */
503+ public static Reader newReader(ReadableByteChannel ch,
504+ CharsetDecoder dec,
505+ int minBufferCap)
506+ {
507+ checkNotNull(ch, "ch");
508+ return StreamDecoder.forDecoder(ch, dec.reset(), minBufferCap);
509+ }
510+
511+ /**
512+ * Constructs a reader that decodes bytes from the given channel according
513+ * to the named charset.
514+ *
515+ * <p> An invocation of this method of the form
516+ *
517+ * <blockquote><pre>
518+ * Channels.newReader(ch, csname)</pre></blockquote>
519+ *
520+ * behaves in exactly the same way as the expression
521+ *
522+ * <blockquote><pre>
523+ * Channels.newReader(ch,
524+ * Charset.forName(csName)
525+ * .newDecoder(),
526+ * -1);</pre></blockquote>
527+ *
528+ * @param ch
529+ * The channel from which bytes will be read
530+ *
531+ * @param csName
532+ * The name of the charset to be used
533+ *
534+ * @return A new reader
535+ *
536+ * @throws UnsupportedCharsetException
537+ * If no support for the named charset is available
538+ * in this instance of the Java virtual machine
539+ */
540+ public static Reader newReader(ReadableByteChannel ch,
541+ String csName)
542+ {
543+ checkNotNull(csName, "csName");
544+ return newReader(ch, Charset.forName(csName).newDecoder(), -1);
545+ }
546+
547+ /**
548+ * Constructs a writer that encodes characters using the given encoder and
549+ * writes the resulting bytes to the given channel.
550+ *
551+ * <p> The resulting stream will contain an internal output buffer of at
552+ * least <tt>minBufferCap</tt> bytes. The stream's <tt>write</tt> methods
553+ * will, as needed, flush the buffer by writing bytes to the underlying
554+ * channel; if the channel is in non-blocking mode when bytes are to be
555+ * written then an {@link IllegalBlockingModeException} will be thrown.
556+ * The resulting stream will not otherwise be buffered. Closing the stream
557+ * will in turn cause the channel to be closed. </p>
558+ *
559+ * @param ch
560+ * The channel to which bytes will be written
561+ *
562+ * @param enc
563+ * The charset encoder to be used
564+ *
565+ * @param minBufferCap
566+ * The minimum capacity of the internal byte buffer,
567+ * or <tt>-1</tt> if an implementation-dependent
568+ * default capacity is to be used
569+ *
570+ * @return A new writer
571+ */
572+ public static Writer newWriter(final WritableByteChannel ch,
573+ final CharsetEncoder enc,
574+ final int minBufferCap)
575+ {
576+ checkNotNull(ch, "ch");
577+ return StreamEncoder.forEncoder(ch, enc.reset(), minBufferCap);
578+ }
579+
580+ /**
581+ * Constructs a writer that encodes characters according to the named
582+ * charset and writes the resulting bytes to the given channel.
583+ *
584+ * <p> An invocation of this method of the form
585+ *
586+ * <blockquote><pre>
587+ * Channels.newWriter(ch, csname)</pre></blockquote>
588+ *
589+ * behaves in exactly the same way as the expression
590+ *
591+ * <blockquote><pre>
592+ * Channels.newWriter(ch,
593+ * Charset.forName(csName)
594+ * .newEncoder(),
595+ * -1);</pre></blockquote>
596+ *
597+ * @param ch
598+ * The channel to which bytes will be written
599+ *
600+ * @param csName
601+ * The name of the charset to be used
602+ *
603+ * @return A new writer
604+ *
605+ * @throws UnsupportedCharsetException
606+ * If no support for the named charset is available
607+ * in this instance of the Java virtual machine
608+ */
609+ public static Writer newWriter(WritableByteChannel ch,
610+ String csName)
611+ {
612+ checkNotNull(csName, "csName");
613+ return newWriter(ch, Charset.forName(csName).newEncoder(), -1);
614+ }
615+}
java/pkg/java/nio/channels/CompletionHandler.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/CompletionHandler.java+66−0
@@ -0,0 +1,66 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+/**
29+ * A handler for consuming the result of an asynchronous I/O operation.
30+ *
31+ * <p> The asynchronous channels defined in this package allow a completion
32+ * handler to be specified to consume the result of an asynchronous operation.
33+ * The {@link #completed completed} method is invoked when the I/O operation
34+ * completes successfully. The {@link #failed failed} method is invoked if the
35+ * I/O operations fails. The implementations of these methods should complete
36+ * in a timely manner so as to avoid keeping the invoking thread from dispatching
37+ * to other completion handlers.
38+ *
39+ * @param <V> The result type of the I/O operation
40+ * @param <A> The type of the object attached to the I/O operation
41+ *
42+ * @since 1.7
43+ */
44+
45+public interface CompletionHandler<V,A> {
46+
47+ /**
48+ * Invoked when an operation has completed.
49+ *
50+ * @param result
51+ * The result of the I/O operation.
52+ * @param attachment
53+ * The object attached to the I/O operation when it was initiated.
54+ */
55+ void completed(V result, A attachment);
56+
57+ /**
58+ * Invoked when an operation fails.
59+ *
60+ * @param exc
61+ * The exception to indicate why the I/O operation failed
62+ * @param attachment
63+ * The object attached to the I/O operation when it was initiated.
64+ */
65+ void failed(Throwable exc, A attachment);
66+}
java/pkg/java/nio/channels/DatagramChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/DatagramChannel.java+568−0
@@ -0,0 +1,568 @@
1+/*
2+ * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.net.ProtocolFamily;
30+import java.net.DatagramSocket;
31+import java.net.SocketOption;
32+import java.net.SocketAddress;
33+import java.nio.ByteBuffer;
34+import java.nio.channels.spi.AbstractSelectableChannel;
35+import java.nio.channels.spi.SelectorProvider;
36+
37+/**
38+ * A selectable channel for datagram-oriented sockets.
39+ *
40+ * <p> A datagram channel is created by invoking one of the {@link #open open} methods
41+ * of this class. It is not possible to create a channel for an arbitrary,
42+ * pre-existing datagram socket. A newly-created datagram channel is open but not
43+ * connected. A datagram channel need not be connected in order for the {@link #send
44+ * send} and {@link #receive receive} methods to be used. A datagram channel may be
45+ * connected, by invoking its {@link #connect connect} method, in order to
46+ * avoid the overhead of the security checks are otherwise performed as part of
47+ * every send and receive operation. A datagram channel must be connected in
48+ * order to use the {@link #read(java.nio.ByteBuffer) read} and {@link
49+ * #write(java.nio.ByteBuffer) write} methods, since those methods do not
50+ * accept or return socket addresses.
51+ *
52+ * <p> Once connected, a datagram channel remains connected until it is
53+ * disconnected or closed. Whether or not a datagram channel is connected may
54+ * be determined by invoking its {@link #isConnected isConnected} method.
55+ *
56+ * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
57+ * setOption} method. A datagram channel to an Internet Protocol socket supports
58+ * the following options:
59+ * <blockquote>
60+ * <table border>
61+ * <tr>
62+ * <th>Option Name</th>
63+ * <th>Description</th>
64+ * </tr>
65+ * <tr>
66+ * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td>
67+ * <td> The size of the socket send buffer </td>
68+ * </tr>
69+ * <tr>
70+ * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
71+ * <td> The size of the socket receive buffer </td>
72+ * </tr>
73+ * <tr>
74+ * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
75+ * <td> Re-use address </td>
76+ * </tr>
77+ * <tr>
78+ * <td> {@link java.net.StandardSocketOptions#SO_BROADCAST SO_BROADCAST} </td>
79+ * <td> Allow transmission of broadcast datagrams </td>
80+ * </tr>
81+ * <tr>
82+ * <td> {@link java.net.StandardSocketOptions#IP_TOS IP_TOS} </td>
83+ * <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td>
84+ * </tr>
85+ * <tr>
86+ * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </td>
87+ * <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
88+ * </tr>
89+ * <tr>
90+ * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
91+ * IP_MULTICAST_TTL} </td>
92+ * <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
93+ * datagrams </td>
94+ * </tr>
95+ * <tr>
96+ * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
97+ * IP_MULTICAST_LOOP} </td>
98+ * <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
99+ * </tr>
100+ * </table>
101+ * </blockquote>
102+ * Additional (implementation specific) options may also be supported.
103+ *
104+ * <p> Datagram channels are safe for use by multiple concurrent threads. They
105+ * support concurrent reading and writing, though at most one thread may be
106+ * reading and at most one thread may be writing at any given time. </p>
107+ *
108+ * @author Mark Reinhold
109+ * @author JSR-51 Expert Group
110+ * @since 1.4
111+ */
112+
113+public abstract class DatagramChannel
114+ extends AbstractSelectableChannel
115+ implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, MulticastChannel
116+{
117+
118+ /**
119+ * Initializes a new instance of this class.
120+ */
121+ protected DatagramChannel(SelectorProvider provider) {
122+ super(provider);
123+ }
124+
125+ /**
126+ * Opens a datagram channel.
127+ *
128+ * <p> The new channel is created by invoking the {@link
129+ * java.nio.channels.spi.SelectorProvider#openDatagramChannel()
130+ * openDatagramChannel} method of the system-wide default {@link
131+ * java.nio.channels.spi.SelectorProvider} object. The channel will not be
132+ * connected.
133+ *
134+ * <p> The {@link ProtocolFamily ProtocolFamily} of the channel's socket
135+ * is platform (and possibly configuration) dependent and therefore unspecified.
136+ * The {@link #open(ProtocolFamily) open} allows the protocol family to be
137+ * selected when opening a datagram channel, and should be used to open
138+ * datagram channels that are intended for Internet Protocol multicasting.
139+ *
140+ * @return A new datagram channel
141+ *
142+ * @throws IOException
143+ * If an I/O error occurs
144+ */
145+ public static DatagramChannel open() throws IOException {
146+ return SelectorProvider.provider().openDatagramChannel();
147+ }
148+
149+ /**
150+ * Opens a datagram channel.
151+ *
152+ * <p> The {@code family} parameter is used to specify the {@link
153+ * ProtocolFamily}. If the datagram channel is to be used for IP multicasing
154+ * then this should correspond to the address type of the multicast groups
155+ * that this channel will join.
156+ *
157+ * <p> The new channel is created by invoking the {@link
158+ * java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily)
159+ * openDatagramChannel} method of the system-wide default {@link
160+ * java.nio.channels.spi.SelectorProvider} object. The channel will not be
161+ * connected.
162+ *
163+ * @param family
164+ * The protocol family
165+ *
166+ * @return A new datagram channel
167+ *
168+ * @throws UnsupportedOperationException
169+ * If the specified protocol family is not supported. For example,
170+ * suppose the parameter is specified as {@link
171+ * java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6}
172+ * but IPv6 is not enabled on the platform.
173+ * @throws IOException
174+ * If an I/O error occurs
175+ *
176+ * @since 1.7
177+ */
178+ public static DatagramChannel open(ProtocolFamily family) throws IOException {
179+ return SelectorProvider.provider().openDatagramChannel(family);
180+ }
181+
182+ /**
183+ * Returns an operation set identifying this channel's supported
184+ * operations.
185+ *
186+ * <p> Datagram channels support reading and writing, so this method
187+ * returns <tt>(</tt>{@link SelectionKey#OP_READ} <tt>|</tt>&nbsp;{@link
188+ * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
189+ *
190+ * @return The valid-operation set
191+ */
192+ public final int validOps() {
193+ return (SelectionKey.OP_READ
194+ | SelectionKey.OP_WRITE);
195+ }
196+
197+
198+ // -- Socket-specific operations --
199+
200+ /**
201+ * @throws AlreadyBoundException {@inheritDoc}
202+ * @throws UnsupportedAddressTypeException {@inheritDoc}
203+ * @throws ClosedChannelException {@inheritDoc}
204+ * @throws IOException {@inheritDoc}
205+ * @throws SecurityException
206+ * If a security manager has been installed and its {@link
207+ * SecurityManager#checkListen checkListen} method denies the
208+ * operation
209+ *
210+ * @since 1.7
211+ */
212+ public abstract DatagramChannel bind(SocketAddress local)
213+ throws IOException;
214+
215+ /**
216+ * @throws UnsupportedOperationException {@inheritDoc}
217+ * @throws IllegalArgumentException {@inheritDoc}
218+ * @throws ClosedChannelException {@inheritDoc}
219+ * @throws IOException {@inheritDoc}
220+ *
221+ * @since 1.7
222+ */
223+ public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value)
224+ throws IOException;
225+
226+ /**
227+ * Retrieves a datagram socket associated with this channel.
228+ *
229+ * <p> The returned object will not declare any public methods that are not
230+ * declared in the {@link java.net.DatagramSocket} class. </p>
231+ *
232+ * @return A datagram socket associated with this channel
233+ */
234+ public abstract DatagramSocket socket();
235+
236+ /**
237+ * Tells whether or not this channel's socket is connected.
238+ *
239+ * @return {@code true} if, and only if, this channel's socket
240+ * is {@link #isOpen open} and connected
241+ */
242+ public abstract boolean isConnected();
243+
244+ /**
245+ * Connects this channel's socket.
246+ *
247+ * <p> The channel's socket is configured so that it only receives
248+ * datagrams from, and sends datagrams to, the given remote <i>peer</i>
249+ * address. Once connected, datagrams may not be received from or sent to
250+ * any other address. A datagram socket remains connected until it is
251+ * explicitly disconnected or until it is closed.
252+ *
253+ * <p> This method performs exactly the same security checks as the {@link
254+ * java.net.DatagramSocket#connect connect} method of the {@link
255+ * java.net.DatagramSocket} class. That is, if a security manager has been
256+ * installed then this method verifies that its {@link
257+ * java.lang.SecurityManager#checkAccept checkAccept} and {@link
258+ * java.lang.SecurityManager#checkConnect checkConnect} methods permit
259+ * datagrams to be received from and sent to, respectively, the given
260+ * remote address.
261+ *
262+ * <p> This method may be invoked at any time. It will not have any effect
263+ * on read or write operations that are already in progress at the moment
264+ * that it is invoked. If this channel's socket is not bound then this method
265+ * will first cause the socket to be bound to an address that is assigned
266+ * automatically, as if invoking the {@link #bind bind} method with a
267+ * parameter of {@code null}. </p>
268+ *
269+ * @param remote
270+ * The remote address to which this channel is to be connected
271+ *
272+ * @return This datagram channel
273+ *
274+ * @throws ClosedChannelException
275+ * If this channel is closed
276+ *
277+ * @throws AsynchronousCloseException
278+ * If another thread closes this channel
279+ * while the connect operation is in progress
280+ *
281+ * @throws ClosedByInterruptException
282+ * If another thread interrupts the current thread
283+ * while the connect operation is in progress, thereby
284+ * closing the channel and setting the current thread's
285+ * interrupt status
286+ *
287+ * @throws SecurityException
288+ * If a security manager has been installed
289+ * and it does not permit access to the given remote address
290+ *
291+ * @throws IOException
292+ * If some other I/O error occurs
293+ */
294+ public abstract DatagramChannel connect(SocketAddress remote)
295+ throws IOException;
296+
297+ /**
298+ * Disconnects this channel's socket.
299+ *
300+ * <p> The channel's socket is configured so that it can receive datagrams
301+ * from, and sends datagrams to, any remote address so long as the security
302+ * manager, if installed, permits it.
303+ *
304+ * <p> This method may be invoked at any time. It will not have any effect
305+ * on read or write operations that are already in progress at the moment
306+ * that it is invoked.
307+ *
308+ * <p> If this channel's socket is not connected, or if the channel is
309+ * closed, then invoking this method has no effect. </p>
310+ *
311+ * @return This datagram channel
312+ *
313+ * @throws IOException
314+ * If some other I/O error occurs
315+ */
316+ public abstract DatagramChannel disconnect() throws IOException;
317+
318+ /**
319+ * Returns the remote address to which this channel's socket is connected.
320+ *
321+ * @return The remote address; {@code null} if the channel's socket is not
322+ * connected
323+ *
324+ * @throws ClosedChannelException
325+ * If the channel is closed
326+ * @throws IOException
327+ * If an I/O error occurs
328+ *
329+ * @since 1.7
330+ */
331+ public abstract SocketAddress getRemoteAddress() throws IOException;
332+
333+ /**
334+ * Receives a datagram via this channel.
335+ *
336+ * <p> If a datagram is immediately available, or if this channel is in
337+ * blocking mode and one eventually becomes available, then the datagram is
338+ * copied into the given byte buffer and its source address is returned.
339+ * If this channel is in non-blocking mode and a datagram is not
340+ * immediately available then this method immediately returns
341+ * <tt>null</tt>.
342+ *
343+ * <p> The datagram is transferred into the given byte buffer starting at
344+ * its current position, as if by a regular {@link
345+ * ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there
346+ * are fewer bytes remaining in the buffer than are required to hold the
347+ * datagram then the remainder of the datagram is silently discarded.
348+ *
349+ * <p> This method performs exactly the same security checks as the {@link
350+ * java.net.DatagramSocket#receive receive} method of the {@link
351+ * java.net.DatagramSocket} class. That is, if the socket is not connected
352+ * to a specific remote address and a security manager has been installed
353+ * then for each datagram received this method verifies that the source's
354+ * address and port number are permitted by the security manager's {@link
355+ * java.lang.SecurityManager#checkAccept checkAccept} method. The overhead
356+ * of this security check can be avoided by first connecting the socket via
357+ * the {@link #connect connect} method.
358+ *
359+ * <p> This method may be invoked at any time. If another thread has
360+ * already initiated a read operation upon this channel, however, then an
361+ * invocation of this method will block until the first operation is
362+ * complete. If this channel's socket is not bound then this method will
363+ * first cause the socket to be bound to an address that is assigned
364+ * automatically, as if invoking the {@link #bind bind} method with a
365+ * parameter of {@code null}. </p>
366+ *
367+ * @param dst
368+ * The buffer into which the datagram is to be transferred
369+ *
370+ * @return The datagram's source address,
371+ * or <tt>null</tt> if this channel is in non-blocking mode
372+ * and no datagram was immediately available
373+ *
374+ * @throws ClosedChannelException
375+ * If this channel is closed
376+ *
377+ * @throws AsynchronousCloseException
378+ * If another thread closes this channel
379+ * while the read operation is in progress
380+ *
381+ * @throws ClosedByInterruptException
382+ * If another thread interrupts the current thread
383+ * while the read operation is in progress, thereby
384+ * closing the channel and setting the current thread's
385+ * interrupt status
386+ *
387+ * @throws SecurityException
388+ * If a security manager has been installed
389+ * and it does not permit datagrams to be accepted
390+ * from the datagram's sender
391+ *
392+ * @throws IOException
393+ * If some other I/O error occurs
394+ */
395+ public abstract SocketAddress receive(ByteBuffer dst) throws IOException;
396+
397+ /**
398+ * Sends a datagram via this channel.
399+ *
400+ * <p> If this channel is in non-blocking mode and there is sufficient room
401+ * in the underlying output buffer, or if this channel is in blocking mode
402+ * and sufficient room becomes available, then the remaining bytes in the
403+ * given buffer are transmitted as a single datagram to the given target
404+ * address.
405+ *
406+ * <p> The datagram is transferred from the byte buffer as if by a regular
407+ * {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation.
408+ *
409+ * <p> This method performs exactly the same security checks as the {@link
410+ * java.net.DatagramSocket#send send} method of the {@link
411+ * java.net.DatagramSocket} class. That is, if the socket is not connected
412+ * to a specific remote address and a security manager has been installed
413+ * then for each datagram sent this method verifies that the target address
414+ * and port number are permitted by the security manager's {@link
415+ * java.lang.SecurityManager#checkConnect checkConnect} method. The
416+ * overhead of this security check can be avoided by first connecting the
417+ * socket via the {@link #connect connect} method.
418+ *
419+ * <p> This method may be invoked at any time. If another thread has
420+ * already initiated a write operation upon this channel, however, then an
421+ * invocation of this method will block until the first operation is
422+ * complete. If this channel's socket is not bound then this method will
423+ * first cause the socket to be bound to an address that is assigned
424+ * automatically, as if by invoking the {@link #bind bind} method with a
425+ * parameter of {@code null}. </p>
426+ *
427+ * @param src
428+ * The buffer containing the datagram to be sent
429+ *
430+ * @param target
431+ * The address to which the datagram is to be sent
432+ *
433+ * @return The number of bytes sent, which will be either the number
434+ * of bytes that were remaining in the source buffer when this
435+ * method was invoked or, if this channel is non-blocking, may be
436+ * zero if there was insufficient room for the datagram in the
437+ * underlying output buffer
438+ *
439+ * @throws ClosedChannelException
440+ * If this channel is closed
441+ *
442+ * @throws AsynchronousCloseException
443+ * If another thread closes this channel
444+ * while the read operation is in progress
445+ *
446+ * @throws ClosedByInterruptException
447+ * If another thread interrupts the current thread
448+ * while the read operation is in progress, thereby
449+ * closing the channel and setting the current thread's
450+ * interrupt status
451+ *
452+ * @throws SecurityException
453+ * If a security manager has been installed
454+ * and it does not permit datagrams to be sent
455+ * to the given address
456+ *
457+ * @throws IOException
458+ * If some other I/O error occurs
459+ */
460+ public abstract int send(ByteBuffer src, SocketAddress target)
461+ throws IOException;
462+
463+
464+ // -- ByteChannel operations --
465+
466+ /**
467+ * Reads a datagram from this channel.
468+ *
469+ * <p> This method may only be invoked if this channel's socket is
470+ * connected, and it only accepts datagrams from the socket's peer. If
471+ * there are more bytes in the datagram than remain in the given buffer
472+ * then the remainder of the datagram is silently discarded. Otherwise
473+ * this method behaves exactly as specified in the {@link
474+ * ReadableByteChannel} interface. </p>
475+ *
476+ * @throws NotYetConnectedException
477+ * If this channel's socket is not connected
478+ */
479+ public abstract int read(ByteBuffer dst) throws IOException;
480+
481+ /**
482+ * Reads a datagram from this channel.
483+ *
484+ * <p> This method may only be invoked if this channel's socket is
485+ * connected, and it only accepts datagrams from the socket's peer. If
486+ * there are more bytes in the datagram than remain in the given buffers
487+ * then the remainder of the datagram is silently discarded. Otherwise
488+ * this method behaves exactly as specified in the {@link
489+ * ScatteringByteChannel} interface. </p>
490+ *
491+ * @throws NotYetConnectedException
492+ * If this channel's socket is not connected
493+ */
494+ public abstract long read(ByteBuffer[] dsts, int offset, int length)
495+ throws IOException;
496+
497+ /**
498+ * Reads a datagram from this channel.
499+ *
500+ * <p> This method may only be invoked if this channel's socket is
501+ * connected, and it only accepts datagrams from the socket's peer. If
502+ * there are more bytes in the datagram than remain in the given buffers
503+ * then the remainder of the datagram is silently discarded. Otherwise
504+ * this method behaves exactly as specified in the {@link
505+ * ScatteringByteChannel} interface. </p>
506+ *
507+ * @throws NotYetConnectedException
508+ * If this channel's socket is not connected
509+ */
510+ public final long read(ByteBuffer[] dsts) throws IOException {
511+ return read(dsts, 0, dsts.length);
512+ }
513+
514+ /**
515+ * Writes a datagram to this channel.
516+ *
517+ * <p> This method may only be invoked if this channel's socket is
518+ * connected, in which case it sends datagrams directly to the socket's
519+ * peer. Otherwise it behaves exactly as specified in the {@link
520+ * WritableByteChannel} interface. </p>
521+ *
522+ * @throws NotYetConnectedException
523+ * If this channel's socket is not connected
524+ */
525+ public abstract int write(ByteBuffer src) throws IOException;
526+
527+ /**
528+ * Writes a datagram to this channel.
529+ *
530+ * <p> This method may only be invoked if this channel's socket is
531+ * connected, in which case it sends datagrams directly to the socket's
532+ * peer. Otherwise it behaves exactly as specified in the {@link
533+ * GatheringByteChannel} interface. </p>
534+ *
535+ * @return The number of bytes sent, which will be either the number
536+ * of bytes that were remaining in the source buffer when this
537+ * method was invoked or, if this channel is non-blocking, may be
538+ * zero if there was insufficient room for the datagram in the
539+ * underlying output buffer
540+ *
541+ * @throws NotYetConnectedException
542+ * If this channel's socket is not connected
543+ */
544+ public abstract long write(ByteBuffer[] srcs, int offset, int length)
545+ throws IOException;
546+
547+ /**
548+ * Writes a datagram to this channel.
549+ *
550+ * <p> This method may only be invoked if this channel's socket is
551+ * connected, in which case it sends datagrams directly to the socket's
552+ * peer. Otherwise it behaves exactly as specified in the {@link
553+ * GatheringByteChannel} interface. </p>
554+ *
555+ * @return The number of bytes sent, which will be either the number
556+ * of bytes that were remaining in the source buffer when this
557+ * method was invoked or, if this channel is non-blocking, may be
558+ * zero if there was insufficient room for the datagram in the
559+ * underlying output buffer
560+ *
561+ * @throws NotYetConnectedException
562+ * If this channel's socket is not connected
563+ */
564+ public final long write(ByteBuffer[] srcs) throws IOException {
565+ return write(srcs, 0, srcs.length);
566+ }
567+
568+}
java/pkg/java/nio/channels/FileChannel$MapMode.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/FileChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/FileChannel.java+1157−0
@@ -0,0 +1,1157 @@
1+/*
2+ * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.*;
29+import java.nio.ByteBuffer;
30+import java.nio.MappedByteBuffer;
31+import java.nio.channels.spi.AbstractInterruptibleChannel;
32+import java.nio.file.*;
33+import java.nio.file.attribute.FileAttribute;
34+import java.nio.file.spi.*;
35+import java.util.Set;
36+import java.util.HashSet;
37+import java.util.Collections;
38+
39+/**
40+ * A channel for reading, writing, mapping, and manipulating a file.
41+ *
42+ * <p> A file channel is a {@link SeekableByteChannel} that is connected to
43+ * a file. It has a current <i>position</i> within its file which can
44+ * be both {@link #position() <i>queried</i>} and {@link #position(long)
45+ * <i>modified</i>}. The file itself contains a variable-length sequence
46+ * of bytes that can be read and written and whose current {@link #size
47+ * <i>size</i>} can be queried. The size of the file increases
48+ * when bytes are written beyond its current size; the size of the file
49+ * decreases when it is {@link #truncate </code><i>truncated</i><code>}. The
50+ * file may also have some associated <i>metadata</i> such as access
51+ * permissions, content type, and last-modification time; this class does not
52+ * define methods for metadata access.
53+ *
54+ * <p> In addition to the familiar read, write, and close operations of byte
55+ * channels, this class defines the following file-specific operations: </p>
56+ *
57+ * <ul>
58+ *
59+ * <li><p> Bytes may be {@link #read(ByteBuffer, long) read} or
60+ * {@link #write(ByteBuffer, long) <i>written</i>} at an absolute
61+ * position in a file in a way that does not affect the channel's current
62+ * position. </p></li>
63+ *
64+ * <li><p> A region of a file may be {@link #map <i>mapped</i>}
65+ * directly into memory; for large files this is often much more efficient
66+ * than invoking the usual <tt>read</tt> or <tt>write</tt> methods.
67+ * </p></li>
68+ *
69+ * <li><p> Updates made to a file may be {@link #force <i>forced
70+ * out</i>} to the underlying storage device, ensuring that data are not
71+ * lost in the event of a system crash. </p></li>
72+ *
73+ * <li><p> Bytes can be transferred from a file {@link #transferTo <i>to
74+ * some other channel</i>}, and {@link #transferFrom <i>vice
75+ * versa</i>}, in a way that can be optimized by many operating systems
76+ * into a very fast transfer directly to or from the filesystem cache.
77+ * </p></li>
78+ *
79+ * <li><p> A region of a file may be {@link FileLock <i>locked</i>}
80+ * against access by other programs. </p></li>
81+ *
82+ * </ul>
83+ *
84+ * <p> File channels are safe for use by multiple concurrent threads. The
85+ * {@link Channel#close close} method may be invoked at any time, as specified
86+ * by the {@link Channel} interface. Only one operation that involves the
87+ * channel's position or can change its file's size may be in progress at any
88+ * given time; attempts to initiate a second such operation while the first is
89+ * still in progress will block until the first operation completes. Other
90+ * operations, in particular those that take an explicit position, may proceed
91+ * concurrently; whether they in fact do so is dependent upon the underlying
92+ * implementation and is therefore unspecified.
93+ *
94+ * <p> The view of a file provided by an instance of this class is guaranteed
95+ * to be consistent with other views of the same file provided by other
96+ * instances in the same program. The view provided by an instance of this
97+ * class may or may not, however, be consistent with the views seen by other
98+ * concurrently-running programs due to caching performed by the underlying
99+ * operating system and delays induced by network-filesystem protocols. This
100+ * is true regardless of the language in which these other programs are
101+ * written, and whether they are running on the same machine or on some other
102+ * machine. The exact nature of any such inconsistencies are system-dependent
103+ * and are therefore unspecified.
104+ *
105+ * <p> A file channel is created by invoking one of the {@link #open open}
106+ * methods defined by this class. A file channel can also be obtained from an
107+ * existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link
108+ * java.io.FileOutputStream#getChannel FileOutputStream}, or {@link
109+ * java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking
110+ * that object's <tt>getChannel</tt> method, which returns a file channel that
111+ * is connected to the same underlying file. Where the file channel is obtained
112+ * from an existing stream or random access file then the state of the file
113+ * channel is intimately connected to that of the object whose <tt>getChannel</tt>
114+ * method returned the channel. Changing the channel's position, whether
115+ * explicitly or by reading or writing bytes, will change the file position of
116+ * the originating object, and vice versa. Changing the file's length via the
117+ * file channel will change the length seen via the originating object, and vice
118+ * versa. Changing the file's content by writing bytes will change the content
119+ * seen by the originating object, and vice versa.
120+ *
121+ * <a name="open-mode"></a> <p> At various points this class specifies that an
122+ * instance that is "open for reading," "open for writing," or "open for
123+ * reading and writing" is required. A channel obtained via the {@link
124+ * java.io.FileInputStream#getChannel getChannel} method of a {@link
125+ * java.io.FileInputStream} instance will be open for reading. A channel
126+ * obtained via the {@link java.io.FileOutputStream#getChannel getChannel}
127+ * method of a {@link java.io.FileOutputStream} instance will be open for
128+ * writing. Finally, a channel obtained via the {@link
129+ * java.io.RandomAccessFile#getChannel getChannel} method of a {@link
130+ * java.io.RandomAccessFile} instance will be open for reading if the instance
131+ * was created with mode <tt>"r"</tt> and will be open for reading and writing
132+ * if the instance was created with mode <tt>"rw"</tt>.
133+ *
134+ * <a name="append-mode"></a><p> A file channel that is open for writing may be in
135+ * <i>append mode</i>, for example if it was obtained from a file-output stream
136+ * that was created by invoking the {@link
137+ * java.io.FileOutputStream#FileOutputStream(java.io.File,boolean)
138+ * FileOutputStream(File,boolean)} constructor and passing <tt>true</tt> for
139+ * the second parameter. In this mode each invocation of a relative write
140+ * operation first advances the position to the end of the file and then writes
141+ * the requested data. Whether the advancement of the position and the writing
142+ * of the data are done in a single atomic operation is system-dependent and
143+ * therefore unspecified.
144+ *
145+ * @see java.io.FileInputStream#getChannel()
146+ * @see java.io.FileOutputStream#getChannel()
147+ * @see java.io.RandomAccessFile#getChannel()
148+ *
149+ * @author Mark Reinhold
150+ * @author Mike McCloskey
151+ * @author JSR-51 Expert Group
152+ * @since 1.4
153+ */
154+
155+public abstract class FileChannel
156+ extends AbstractInterruptibleChannel
157+ implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel
158+{
159+ /**
160+ * Initializes a new instance of this class.
161+ */
162+ protected FileChannel() { }
163+
164+ /**
165+ * Opens or creates a file, returning a file channel to access the file.
166+ *
167+ * <p> The {@code options} parameter determines how the file is opened.
168+ * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE
169+ * WRITE} options determine if the file should be opened for reading and/or
170+ * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND}
171+ * option) is contained in the array then the file is opened for reading.
172+ * By default reading or writing commences at the beginning of the file.
173+ *
174+ * <p> In the addition to {@code READ} and {@code WRITE}, the following
175+ * options may be present:
176+ *
177+ * <table border=1 cellpadding=5 summary="">
178+ * <tr> <th>Option</th> <th>Description</th> </tr>
179+ * <tr>
180+ * <td> {@link StandardOpenOption#APPEND APPEND} </td>
181+ * <td> If this option is present then the file is opened for writing and
182+ * each invocation of the channel's {@code write} method first advances
183+ * the position to the end of the file and then writes the requested
184+ * data. Whether the advancement of the position and the writing of the
185+ * data are done in a single atomic operation is system-dependent and
186+ * therefore unspecified. This option may not be used in conjunction
187+ * with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
188+ * </tr>
189+ * <tr>
190+ * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td>
191+ * <td> If this option is present then the existing file is truncated to
192+ * a size of 0 bytes. This option is ignored when the file is opened only
193+ * for reading. </td>
194+ * </tr>
195+ * <tr>
196+ * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td>
197+ * <td> If this option is present then a new file is created, failing if
198+ * the file already exists. When creating a file the check for the
199+ * existence of the file and the creation of the file if it does not exist
200+ * is atomic with respect to other file system operations. This option is
201+ * ignored when the file is opened only for reading. </td>
202+ * </tr>
203+ * <tr>
204+ * <td > {@link StandardOpenOption#CREATE CREATE} </td>
205+ * <td> If this option is present then an existing file is opened if it
206+ * exists, otherwise a new file is created. When creating a file the check
207+ * for the existence of the file and the creation of the file if it does
208+ * not exist is atomic with respect to other file system operations. This
209+ * option is ignored if the {@code CREATE_NEW} option is also present or
210+ * the file is opened only for reading. </td>
211+ * </tr>
212+ * <tr>
213+ * <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td>
214+ * <td> When this option is present then the implementation makes a
215+ * <em>best effort</em> attempt to delete the file when closed by the
216+ * the {@link #close close} method. If the {@code close} method is not
217+ * invoked then a <em>best effort</em> attempt is made to delete the file
218+ * when the Java virtual machine terminates. </td>
219+ * </tr>
220+ * <tr>
221+ * <td>{@link StandardOpenOption#SPARSE SPARSE} </td>
222+ * <td> When creating a new file this option is a <em>hint</em> that the
223+ * new file will be sparse. This option is ignored when not creating
224+ * a new file. </td>
225+ * </tr>
226+ * <tr>
227+ * <td> {@link StandardOpenOption#SYNC SYNC} </td>
228+ * <td> Requires that every update to the file's content or metadata be
229+ * written synchronously to the underlying storage device. (see <a
230+ * href="../file/package-summary.html#integrity"> Synchronized I/O file
231+ * integrity</a>). </td>
232+ * <tr>
233+ * <tr>
234+ * <td> {@link StandardOpenOption#DSYNC DSYNC} </td>
235+ * <td> Requires that every update to the file's content be written
236+ * synchronously to the underlying storage device. (see <a
237+ * href="../file/package-summary.html#integrity"> Synchronized I/O file
238+ * integrity</a>). </td>
239+ * </tr>
240+ * </table>
241+ *
242+ * <p> An implementation may also support additional options.
243+ *
244+ * <p> The {@code attrs} parameter is an optional array of file {@link
245+ * FileAttribute file-attributes} to set atomically when creating the file.
246+ *
247+ * <p> The new channel is created by invoking the {@link
248+ * FileSystemProvider#newFileChannel newFileChannel} method on the
249+ * provider that created the {@code Path}.
250+ *
251+ * @param path
252+ * The path of the file to open or create
253+ * @param options
254+ * Options specifying how the file is opened
255+ * @param attrs
256+ * An optional list of file attributes to set atomically when
257+ * creating the file
258+ *
259+ * @return A new file channel
260+ *
261+ * @throws IllegalArgumentException
262+ * If the set contains an invalid combination of options
263+ * @throws UnsupportedOperationException
264+ * If the {@code path} is associated with a provider that does not
265+ * support creating file channels, or an unsupported open option is
266+ * specified, or the array contains an attribute that cannot be set
267+ * atomically when creating the file
268+ * @throws IOException
269+ * If an I/O error occurs
270+ * @throws SecurityException
271+ * If a security manager is installed and it denies an
272+ * unspecified permission required by the implementation.
273+ * In the case of the default provider, the {@link
274+ * SecurityManager#checkRead(String)} method is invoked to check
275+ * read access if the file is opened for reading. The {@link
276+ * SecurityManager#checkWrite(String)} method is invoked to check
277+ * write access if the file is opened for writing
278+ *
279+ * @since 1.7
280+ */
281+ public static FileChannel open(Path path,
282+ Set<? extends OpenOption> options,
283+ FileAttribute<?>... attrs)
284+ throws IOException
285+ {
286+ FileSystemProvider provider = path.getFileSystem().provider();
287+ return provider.newFileChannel(path, options, attrs);
288+ }
289+
290+ private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0];
291+
292+ /**
293+ * Opens or creates a file, returning a file channel to access the file.
294+ *
295+ * <p> An invocation of this method behaves in exactly the same way as the
296+ * invocation
297+ * <pre>
298+ * fc.{@link #open(Path,Set,FileAttribute[]) open}(file, opts, new FileAttribute&lt;?&gt;[0]);
299+ * </pre>
300+ * where {@code opts} is a set of the options specified in the {@code
301+ * options} array.
302+ *
303+ * @param path
304+ * The path of the file to open or create
305+ * @param options
306+ * Options specifying how the file is opened
307+ *
308+ * @return A new file channel
309+ *
310+ * @throws IllegalArgumentException
311+ * If the set contains an invalid combination of options
312+ * @throws UnsupportedOperationException
313+ * If the {@code path} is associated with a provider that does not
314+ * support creating file channels, or an unsupported open option is
315+ * specified
316+ * @throws IOException
317+ * If an I/O error occurs
318+ * @throws SecurityException
319+ * If a security manager is installed and it denies an
320+ * unspecified permission required by the implementation.
321+ * In the case of the default provider, the {@link
322+ * SecurityManager#checkRead(String)} method is invoked to check
323+ * read access if the file is opened for reading. The {@link
324+ * SecurityManager#checkWrite(String)} method is invoked to check
325+ * write access if the file is opened for writing
326+ *
327+ * @since 1.7
328+ */
329+ public static FileChannel open(Path path, OpenOption... options)
330+ throws IOException
331+ {
332+ Set<OpenOption> set = new HashSet<OpenOption>(options.length);
333+ Collections.addAll(set, options);
334+ return open(path, set, NO_ATTRIBUTES);
335+ }
336+
337+ // -- Channel operations --
338+
339+ /**
340+ * Reads a sequence of bytes from this channel into the given buffer.
341+ *
342+ * <p> Bytes are read starting at this channel's current file position, and
343+ * then the file position is updated with the number of bytes actually
344+ * read. Otherwise this method behaves exactly as specified in the {@link
345+ * ReadableByteChannel} interface. </p>
346+ */
347+ public abstract int read(ByteBuffer dst) throws IOException;
348+
349+ /**
350+ * Reads a sequence of bytes from this channel into a subsequence of the
351+ * given buffers.
352+ *
353+ * <p> Bytes are read starting at this channel's current file position, and
354+ * then the file position is updated with the number of bytes actually
355+ * read. Otherwise this method behaves exactly as specified in the {@link
356+ * ScatteringByteChannel} interface. </p>
357+ */
358+ public abstract long read(ByteBuffer[] dsts, int offset, int length)
359+ throws IOException;
360+
361+ /**
362+ * Reads a sequence of bytes from this channel into the given buffers.
363+ *
364+ * <p> Bytes are read starting at this channel's current file position, and
365+ * then the file position is updated with the number of bytes actually
366+ * read. Otherwise this method behaves exactly as specified in the {@link
367+ * ScatteringByteChannel} interface. </p>
368+ */
369+ public final long read(ByteBuffer[] dsts) throws IOException {
370+ return read(dsts, 0, dsts.length);
371+ }
372+
373+ /**
374+ * Writes a sequence of bytes to this channel from the given buffer.
375+ *
376+ * <p> Bytes are written starting at this channel's current file position
377+ * unless the channel is in append mode, in which case the position is
378+ * first advanced to the end of the file. The file is grown, if necessary,
379+ * to accommodate the written bytes, and then the file position is updated
380+ * with the number of bytes actually written. Otherwise this method
381+ * behaves exactly as specified by the {@link WritableByteChannel}
382+ * interface. </p>
383+ */
384+ public abstract int write(ByteBuffer src) throws IOException;
385+
386+ /**
387+ * Writes a sequence of bytes to this channel from a subsequence of the
388+ * given buffers.
389+ *
390+ * <p> Bytes are written starting at this channel's current file position
391+ * unless the channel is in append mode, in which case the position is
392+ * first advanced to the end of the file. The file is grown, if necessary,
393+ * to accommodate the written bytes, and then the file position is updated
394+ * with the number of bytes actually written. Otherwise this method
395+ * behaves exactly as specified in the {@link GatheringByteChannel}
396+ * interface. </p>
397+ */
398+ public abstract long write(ByteBuffer[] srcs, int offset, int length)
399+ throws IOException;
400+
401+ /**
402+ * Writes a sequence of bytes to this channel from the given buffers.
403+ *
404+ * <p> Bytes are written starting at this channel's current file position
405+ * unless the channel is in append mode, in which case the position is
406+ * first advanced to the end of the file. The file is grown, if necessary,
407+ * to accommodate the written bytes, and then the file position is updated
408+ * with the number of bytes actually written. Otherwise this method
409+ * behaves exactly as specified in the {@link GatheringByteChannel}
410+ * interface. </p>
411+ */
412+ public final long write(ByteBuffer[] srcs) throws IOException {
413+ return write(srcs, 0, srcs.length);
414+ }
415+
416+
417+ // -- Other operations --
418+
419+ /**
420+ * Returns this channel's file position. </p>
421+ *
422+ * @return This channel's file position,
423+ * a non-negative integer counting the number of bytes
424+ * from the beginning of the file to the current position
425+ *
426+ * @throws ClosedChannelException
427+ * If this channel is closed
428+ *
429+ * @throws IOException
430+ * If some other I/O error occurs
431+ */
432+ public abstract long position() throws IOException;
433+
434+ /**
435+ * Sets this channel's file position.
436+ *
437+ * <p> Setting the position to a value that is greater than the file's
438+ * current size is legal but does not change the size of the file. A later
439+ * attempt to read bytes at such a position will immediately return an
440+ * end-of-file indication. A later attempt to write bytes at such a
441+ * position will cause the file to be grown to accommodate the new bytes;
442+ * the values of any bytes between the previous end-of-file and the
443+ * newly-written bytes are unspecified. </p>
444+ *
445+ * @param newPosition
446+ * The new position, a non-negative integer counting
447+ * the number of bytes from the beginning of the file
448+ *
449+ * @return This file channel
450+ *
451+ * @throws ClosedChannelException
452+ * If this channel is closed
453+ *
454+ * @throws IllegalArgumentException
455+ * If the new position is negative
456+ *
457+ * @throws IOException
458+ * If some other I/O error occurs
459+ */
460+ public abstract FileChannel position(long newPosition) throws IOException;
461+
462+ /**
463+ * Returns the current size of this channel's file. </p>
464+ *
465+ * @return The current size of this channel's file,
466+ * measured in bytes
467+ *
468+ * @throws ClosedChannelException
469+ * If this channel is closed
470+ *
471+ * @throws IOException
472+ * If some other I/O error occurs
473+ */
474+ public abstract long size() throws IOException;
475+
476+ /**
477+ * Truncates this channel's file to the given size.
478+ *
479+ * <p> If the given size is less than the file's current size then the file
480+ * is truncated, discarding any bytes beyond the new end of the file. If
481+ * the given size is greater than or equal to the file's current size then
482+ * the file is not modified. In either case, if this channel's file
483+ * position is greater than the given size then it is set to that size.
484+ * </p>
485+ *
486+ * @param size
487+ * The new size, a non-negative byte count
488+ *
489+ * @return This file channel
490+ *
491+ * @throws NonWritableChannelException
492+ * If this channel was not opened for writing
493+ *
494+ * @throws ClosedChannelException
495+ * If this channel is closed
496+ *
497+ * @throws IllegalArgumentException
498+ * If the new size is negative
499+ *
500+ * @throws IOException
501+ * If some other I/O error occurs
502+ */
503+ public abstract FileChannel truncate(long size) throws IOException;
504+
505+ /**
506+ * Forces any updates to this channel's file to be written to the storage
507+ * device that contains it.
508+ *
509+ * <p> If this channel's file resides on a local storage device then when
510+ * this method returns it is guaranteed that all changes made to the file
511+ * since this channel was created, or since this method was last invoked,
512+ * will have been written to that device. This is useful for ensuring that
513+ * critical information is not lost in the event of a system crash.
514+ *
515+ * <p> If the file does not reside on a local device then no such guarantee
516+ * is made.
517+ *
518+ * <p> The <tt>metaData</tt> parameter can be used to limit the number of
519+ * I/O operations that this method is required to perform. Passing
520+ * <tt>false</tt> for this parameter indicates that only updates to the
521+ * file's content need be written to storage; passing <tt>true</tt>
522+ * indicates that updates to both the file's content and metadata must be
523+ * written, which generally requires at least one more I/O operation.
524+ * Whether this parameter actually has any effect is dependent upon the
525+ * underlying operating system and is therefore unspecified.
526+ *
527+ * <p> Invoking this method may cause an I/O operation to occur even if the
528+ * channel was only opened for reading. Some operating systems, for
529+ * example, maintain a last-access time as part of a file's metadata, and
530+ * this time is updated whenever the file is read. Whether or not this is
531+ * actually done is system-dependent and is therefore unspecified.
532+ *
533+ * <p> This method is only guaranteed to force changes that were made to
534+ * this channel's file via the methods defined in this class. It may or
535+ * may not force changes that were made by modifying the content of a
536+ * {@link MappedByteBuffer <i>mapped byte buffer</i>} obtained by
537+ * invoking the {@link #map map} method. Invoking the {@link
538+ * MappedByteBuffer#force force} method of the mapped byte buffer will
539+ * force changes made to the buffer's content to be written. </p>
540+ *
541+ * @param metaData
542+ * If <tt>true</tt> then this method is required to force changes
543+ * to both the file's content and metadata to be written to
544+ * storage; otherwise, it need only force content changes to be
545+ * written
546+ *
547+ * @throws ClosedChannelException
548+ * If this channel is closed
549+ *
550+ * @throws IOException
551+ * If some other I/O error occurs
552+ */
553+ public abstract void force(boolean metaData) throws IOException;
554+
555+ /**
556+ * Transfers bytes from this channel's file to the given writable byte
557+ * channel.
558+ *
559+ * <p> An attempt is made to read up to <tt>count</tt> bytes starting at
560+ * the given <tt>position</tt> in this channel's file and write them to the
561+ * target channel. An invocation of this method may or may not transfer
562+ * all of the requested bytes; whether or not it does so depends upon the
563+ * natures and states of the channels. Fewer than the requested number of
564+ * bytes are transferred if this channel's file contains fewer than
565+ * <tt>count</tt> bytes starting at the given <tt>position</tt>, or if the
566+ * target channel is non-blocking and it has fewer than <tt>count</tt>
567+ * bytes free in its output buffer.
568+ *
569+ * <p> This method does not modify this channel's position. If the given
570+ * position is greater than the file's current size then no bytes are
571+ * transferred. If the target channel has a position then bytes are
572+ * written starting at that position and then the position is incremented
573+ * by the number of bytes written.
574+ *
575+ * <p> This method is potentially much more efficient than a simple loop
576+ * that reads from this channel and writes to the target channel. Many
577+ * operating systems can transfer bytes directly from the filesystem cache
578+ * to the target channel without actually copying them. </p>
579+ *
580+ * @param position
581+ * The position within the file at which the transfer is to begin;
582+ * must be non-negative
583+ *
584+ * @param count
585+ * The maximum number of bytes to be transferred; must be
586+ * non-negative
587+ *
588+ * @param target
589+ * The target channel
590+ *
591+ * @return The number of bytes, possibly zero,
592+ * that were actually transferred
593+ *
594+ * @throws IllegalArgumentException
595+ * If the preconditions on the parameters do not hold
596+ *
597+ * @throws NonReadableChannelException
598+ * If this channel was not opened for reading
599+ *
600+ * @throws NonWritableChannelException
601+ * If the target channel was not opened for writing
602+ *
603+ * @throws ClosedChannelException
604+ * If either this channel or the target channel is closed
605+ *
606+ * @throws AsynchronousCloseException
607+ * If another thread closes either channel
608+ * while the transfer is in progress
609+ *
610+ * @throws ClosedByInterruptException
611+ * If another thread interrupts the current thread while the
612+ * transfer is in progress, thereby closing both channels and
613+ * setting the current thread's interrupt status
614+ *
615+ * @throws IOException
616+ * If some other I/O error occurs
617+ */
618+ public abstract long transferTo(long position, long count,
619+ WritableByteChannel target)
620+ throws IOException;
621+
622+ /**
623+ * Transfers bytes into this channel's file from the given readable byte
624+ * channel.
625+ *
626+ * <p> An attempt is made to read up to <tt>count</tt> bytes from the
627+ * source channel and write them to this channel's file starting at the
628+ * given <tt>position</tt>. An invocation of this method may or may not
629+ * transfer all of the requested bytes; whether or not it does so depends
630+ * upon the natures and states of the channels. Fewer than the requested
631+ * number of bytes will be transferred if the source channel has fewer than
632+ * <tt>count</tt> bytes remaining, or if the source channel is non-blocking
633+ * and has fewer than <tt>count</tt> bytes immediately available in its
634+ * input buffer.
635+ *
636+ * <p> This method does not modify this channel's position. If the given
637+ * position is greater than the file's current size then no bytes are
638+ * transferred. If the source channel has a position then bytes are read
639+ * starting at that position and then the position is incremented by the
640+ * number of bytes read.
641+ *
642+ * <p> This method is potentially much more efficient than a simple loop
643+ * that reads from the source channel and writes to this channel. Many
644+ * operating systems can transfer bytes directly from the source channel
645+ * into the filesystem cache without actually copying them. </p>
646+ *
647+ * @param src
648+ * The source channel
649+ *
650+ * @param position
651+ * The position within the file at which the transfer is to begin;
652+ * must be non-negative
653+ *
654+ * @param count
655+ * The maximum number of bytes to be transferred; must be
656+ * non-negative
657+ *
658+ * @return The number of bytes, possibly zero,
659+ * that were actually transferred
660+ *
661+ * @throws IllegalArgumentException
662+ * If the preconditions on the parameters do not hold
663+ *
664+ * @throws NonReadableChannelException
665+ * If the source channel was not opened for reading
666+ *
667+ * @throws NonWritableChannelException
668+ * If this channel was not opened for writing
669+ *
670+ * @throws ClosedChannelException
671+ * If either this channel or the source channel is closed
672+ *
673+ * @throws AsynchronousCloseException
674+ * If another thread closes either channel
675+ * while the transfer is in progress
676+ *
677+ * @throws ClosedByInterruptException
678+ * If another thread interrupts the current thread while the
679+ * transfer is in progress, thereby closing both channels and
680+ * setting the current thread's interrupt status
681+ *
682+ * @throws IOException
683+ * If some other I/O error occurs
684+ */
685+ public abstract long transferFrom(ReadableByteChannel src,
686+ long position, long count)
687+ throws IOException;
688+
689+ /**
690+ * Reads a sequence of bytes from this channel into the given buffer,
691+ * starting at the given file position.
692+ *
693+ * <p> This method works in the same manner as the {@link
694+ * #read(ByteBuffer)} method, except that bytes are read starting at the
695+ * given file position rather than at the channel's current position. This
696+ * method does not modify this channel's position. If the given position
697+ * is greater than the file's current size then no bytes are read. </p>
698+ *
699+ * @param dst
700+ * The buffer into which bytes are to be transferred
701+ *
702+ * @param position
703+ * The file position at which the transfer is to begin;
704+ * must be non-negative
705+ *
706+ * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
707+ * given position is greater than or equal to the file's current
708+ * size
709+ *
710+ * @throws IllegalArgumentException
711+ * If the position is negative
712+ *
713+ * @throws NonReadableChannelException
714+ * If this channel was not opened for reading
715+ *
716+ * @throws ClosedChannelException
717+ * If this channel is closed
718+ *
719+ * @throws AsynchronousCloseException
720+ * If another thread closes this channel
721+ * while the read operation is in progress
722+ *
723+ * @throws ClosedByInterruptException
724+ * If another thread interrupts the current thread
725+ * while the read operation is in progress, thereby
726+ * closing the channel and setting the current thread's
727+ * interrupt status
728+ *
729+ * @throws IOException
730+ * If some other I/O error occurs
731+ */
732+ public abstract int read(ByteBuffer dst, long position) throws IOException;
733+
734+ /**
735+ * Writes a sequence of bytes to this channel from the given buffer,
736+ * starting at the given file position.
737+ *
738+ * <p> This method works in the same manner as the {@link
739+ * #write(ByteBuffer)} method, except that bytes are written starting at
740+ * the given file position rather than at the channel's current position.
741+ * This method does not modify this channel's position. If the given
742+ * position is greater than the file's current size then the file will be
743+ * grown to accommodate the new bytes; the values of any bytes between the
744+ * previous end-of-file and the newly-written bytes are unspecified. </p>
745+ *
746+ * @param src
747+ * The buffer from which bytes are to be transferred
748+ *
749+ * @param position
750+ * The file position at which the transfer is to begin;
751+ * must be non-negative
752+ *
753+ * @return The number of bytes written, possibly zero
754+ *
755+ * @throws IllegalArgumentException
756+ * If the position is negative
757+ *
758+ * @throws NonWritableChannelException
759+ * If this channel was not opened for writing
760+ *
761+ * @throws ClosedChannelException
762+ * If this channel is closed
763+ *
764+ * @throws AsynchronousCloseException
765+ * If another thread closes this channel
766+ * while the write operation is in progress
767+ *
768+ * @throws ClosedByInterruptException
769+ * If another thread interrupts the current thread
770+ * while the write operation is in progress, thereby
771+ * closing the channel and setting the current thread's
772+ * interrupt status
773+ *
774+ * @throws IOException
775+ * If some other I/O error occurs
776+ */
777+ public abstract int write(ByteBuffer src, long position) throws IOException;
778+
779+
780+ // -- Memory-mapped buffers --
781+
782+ /**
783+ * A typesafe enumeration for file-mapping modes.
784+ *
785+ * @since 1.4
786+ *
787+ * @see java.nio.channels.FileChannel#map
788+ */
789+ public static class MapMode {
790+
791+ /**
792+ * Mode for a read-only mapping.
793+ */
794+ public static final MapMode READ_ONLY
795+ = new MapMode("READ_ONLY");
796+
797+ /**
798+ * Mode for a read/write mapping.
799+ */
800+ public static final MapMode READ_WRITE
801+ = new MapMode("READ_WRITE");
802+
803+ /**
804+ * Mode for a private (copy-on-write) mapping.
805+ */
806+ public static final MapMode PRIVATE
807+ = new MapMode("PRIVATE");
808+
809+ private final String name;
810+
811+ private MapMode(String name) {
812+ this.name = name;
813+ }
814+
815+ /**
816+ * Returns a string describing this file-mapping mode.
817+ *
818+ * @return A descriptive string
819+ */
820+ public String toString() {
821+ return name;
822+ }
823+
824+ }
825+
826+ /**
827+ * Maps a region of this channel's file directly into memory.
828+ *
829+ * <p> A region of a file may be mapped into memory in one of three modes:
830+ * </p>
831+ *
832+ * <ul type=disc>
833+ *
834+ * <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer
835+ * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown.
836+ * ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li>
837+ *
838+ * <li><p> <i>Read/write:</i> Changes made to the resulting buffer will
839+ * eventually be propagated to the file; they may or may not be made
840+ * visible to other programs that have mapped the same file. ({@link
841+ * MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li>
842+ *
843+ * <li><p> <i>Private:</i> Changes made to the resulting buffer will not
844+ * be propagated to the file and will not be visible to other programs
845+ * that have mapped the same file; instead, they will cause private
846+ * copies of the modified portions of the buffer to be created. ({@link
847+ * MapMode#PRIVATE MapMode.PRIVATE}) </p></li>
848+ *
849+ * </ul>
850+ *
851+ * <p> For a read-only mapping, this channel must have been opened for
852+ * reading; for a read/write or private mapping, this channel must have
853+ * been opened for both reading and writing.
854+ *
855+ * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>}
856+ * returned by this method will have a position of zero and a limit and
857+ * capacity of <tt>size</tt>; its mark will be undefined. The buffer and
858+ * the mapping that it represents will remain valid until the buffer itself
859+ * is garbage-collected.
860+ *
861+ * <p> A mapping, once established, is not dependent upon the file channel
862+ * that was used to create it. Closing the channel, in particular, has no
863+ * effect upon the validity of the mapping.
864+ *
865+ * <p> Many of the details of memory-mapped files are inherently dependent
866+ * upon the underlying operating system and are therefore unspecified. The
867+ * behavior of this method when the requested region is not completely
868+ * contained within this channel's file is unspecified. Whether changes
869+ * made to the content or size of the underlying file, by this program or
870+ * another, are propagated to the buffer is unspecified. The rate at which
871+ * changes to the buffer are propagated to the file is unspecified.
872+ *
873+ * <p> For most operating systems, mapping a file into memory is more
874+ * expensive than reading or writing a few tens of kilobytes of data via
875+ * the usual {@link #read read} and {@link #write write} methods. From the
876+ * standpoint of performance it is generally only worth mapping relatively
877+ * large files into memory. </p>
878+ *
879+ * @param mode
880+ * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link
881+ * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE
882+ * PRIVATE} defined in the {@link MapMode} class, according to
883+ * whether the file is to be mapped read-only, read/write, or
884+ * privately (copy-on-write), respectively
885+ *
886+ * @param position
887+ * The position within the file at which the mapped region
888+ * is to start; must be non-negative
889+ *
890+ * @param size
891+ * The size of the region to be mapped; must be non-negative and
892+ * no greater than {@link java.lang.Integer#MAX_VALUE}
893+ *
894+ * @return The mapped byte buffer
895+ *
896+ * @throws NonReadableChannelException
897+ * If the <tt>mode</tt> is {@link MapMode#READ_ONLY READ_ONLY} but
898+ * this channel was not opened for reading
899+ *
900+ * @throws NonWritableChannelException
901+ * If the <tt>mode</tt> is {@link MapMode#READ_WRITE READ_WRITE} or
902+ * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened
903+ * for both reading and writing
904+ *
905+ * @throws IllegalArgumentException
906+ * If the preconditions on the parameters do not hold
907+ *
908+ * @throws IOException
909+ * If some other I/O error occurs
910+ *
911+ * @see java.nio.channels.FileChannel.MapMode
912+ * @see java.nio.MappedByteBuffer
913+ */
914+ public abstract MappedByteBuffer map(MapMode mode,
915+ long position, long size)
916+ throws IOException;
917+
918+
919+ // -- Locks --
920+
921+ /**
922+ * Acquires a lock on the given region of this channel's file.
923+ *
924+ * <p> An invocation of this method will block until the region can be
925+ * locked, this channel is closed, or the invoking thread is interrupted,
926+ * whichever comes first.
927+ *
928+ * <p> If this channel is closed by another thread during an invocation of
929+ * this method then an {@link AsynchronousCloseException} will be thrown.
930+ *
931+ * <p> If the invoking thread is interrupted while waiting to acquire the
932+ * lock then its interrupt status will be set and a {@link
933+ * FileLockInterruptionException} will be thrown. If the invoker's
934+ * interrupt status is set when this method is invoked then that exception
935+ * will be thrown immediately; the thread's interrupt status will not be
936+ * changed.
937+ *
938+ * <p> The region specified by the <tt>position</tt> and <tt>size</tt>
939+ * parameters need not be contained within, or even overlap, the actual
940+ * underlying file. Lock regions are fixed in size; if a locked region
941+ * initially contains the end of the file and the file grows beyond the
942+ * region then the new portion of the file will not be covered by the lock.
943+ * If a file is expected to grow in size and a lock on the entire file is
944+ * required then a region starting at zero, and no smaller than the
945+ * expected maximum size of the file, should be locked. The zero-argument
946+ * {@link #lock()} method simply locks a region of size {@link
947+ * Long#MAX_VALUE}.
948+ *
949+ * <p> Some operating systems do not support shared locks, in which case a
950+ * request for a shared lock is automatically converted into a request for
951+ * an exclusive lock. Whether the newly-acquired lock is shared or
952+ * exclusive may be tested by invoking the resulting lock object's {@link
953+ * FileLock#isShared() isShared} method.
954+ *
955+ * <p> File locks are held on behalf of the entire Java virtual machine.
956+ * They are not suitable for controlling access to a file by multiple
957+ * threads within the same virtual machine. </p>
958+ *
959+ * @param position
960+ * The position at which the locked region is to start; must be
961+ * non-negative
962+ *
963+ * @param size
964+ * The size of the locked region; must be non-negative, and the sum
965+ * <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
966+ *
967+ * @param shared
968+ * <tt>true</tt> to request a shared lock, in which case this
969+ * channel must be open for reading (and possibly writing);
970+ * <tt>false</tt> to request an exclusive lock, in which case this
971+ * channel must be open for writing (and possibly reading)
972+ *
973+ * @return A lock object representing the newly-acquired lock
974+ *
975+ * @throws IllegalArgumentException
976+ * If the preconditions on the parameters do not hold
977+ *
978+ * @throws ClosedChannelException
979+ * If this channel is closed
980+ *
981+ * @throws AsynchronousCloseException
982+ * If another thread closes this channel while the invoking
983+ * thread is blocked in this method
984+ *
985+ * @throws FileLockInterruptionException
986+ * If the invoking thread is interrupted while blocked in this
987+ * method
988+ *
989+ * @throws OverlappingFileLockException
990+ * If a lock that overlaps the requested region is already held by
991+ * this Java virtual machine, or if another thread is already
992+ * blocked in this method and is attempting to lock an overlapping
993+ * region
994+ *
995+ * @throws NonReadableChannelException
996+ * If <tt>shared</tt> is <tt>true</tt> this channel was not
997+ * opened for reading
998+ *
999+ * @throws NonWritableChannelException
1000+ * If <tt>shared</tt> is <tt>false</tt> but this channel was not
1001+ * opened for writing
1002+ *
1003+ * @throws IOException
1004+ * If some other I/O error occurs
1005+ *
1006+ * @see #lock()
1007+ * @see #tryLock()
1008+ * @see #tryLock(long,long,boolean)
1009+ */
1010+ public abstract FileLock lock(long position, long size, boolean shared)
1011+ throws IOException;
1012+
1013+ /**
1014+ * Acquires an exclusive lock on this channel's file.
1015+ *
1016+ * <p> An invocation of this method of the form <tt>fc.lock()</tt> behaves
1017+ * in exactly the same way as the invocation
1018+ *
1019+ * <pre>
1020+ * fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre>
1021+ *
1022+ * @return A lock object representing the newly-acquired lock
1023+ *
1024+ * @throws ClosedChannelException
1025+ * If this channel is closed
1026+ *
1027+ * @throws AsynchronousCloseException
1028+ * If another thread closes this channel while the invoking
1029+ * thread is blocked in this method
1030+ *
1031+ * @throws FileLockInterruptionException
1032+ * If the invoking thread is interrupted while blocked in this
1033+ * method
1034+ *
1035+ * @throws OverlappingFileLockException
1036+ * If a lock that overlaps the requested region is already held by
1037+ * this Java virtual machine, or if another thread is already
1038+ * blocked in this method and is attempting to lock an overlapping
1039+ * region of the same file
1040+ *
1041+ * @throws NonWritableChannelException
1042+ * If this channel was not opened for writing
1043+ *
1044+ * @throws IOException
1045+ * If some other I/O error occurs
1046+ *
1047+ * @see #lock(long,long,boolean)
1048+ * @see #tryLock()
1049+ * @see #tryLock(long,long,boolean)
1050+ */
1051+ public final FileLock lock() throws IOException {
1052+ return lock(0L, Long.MAX_VALUE, false);
1053+ }
1054+
1055+ /**
1056+ * Attempts to acquire a lock on the given region of this channel's file.
1057+ *
1058+ * <p> This method does not block. An invocation always returns
1059+ * immediately, either having acquired a lock on the requested region or
1060+ * having failed to do so. If it fails to acquire a lock because an
1061+ * overlapping lock is held by another program then it returns
1062+ * <tt>null</tt>. If it fails to acquire a lock for any other reason then
1063+ * an appropriate exception is thrown.
1064+ *
1065+ * <p> The region specified by the <tt>position</tt> and <tt>size</tt>
1066+ * parameters need not be contained within, or even overlap, the actual
1067+ * underlying file. Lock regions are fixed in size; if a locked region
1068+ * initially contains the end of the file and the file grows beyond the
1069+ * region then the new portion of the file will not be covered by the lock.
1070+ * If a file is expected to grow in size and a lock on the entire file is
1071+ * required then a region starting at zero, and no smaller than the
1072+ * expected maximum size of the file, should be locked. The zero-argument
1073+ * {@link #tryLock()} method simply locks a region of size {@link
1074+ * Long#MAX_VALUE}.
1075+ *
1076+ * <p> Some operating systems do not support shared locks, in which case a
1077+ * request for a shared lock is automatically converted into a request for
1078+ * an exclusive lock. Whether the newly-acquired lock is shared or
1079+ * exclusive may be tested by invoking the resulting lock object's {@link
1080+ * FileLock#isShared() isShared} method.
1081+ *
1082+ * <p> File locks are held on behalf of the entire Java virtual machine.
1083+ * They are not suitable for controlling access to a file by multiple
1084+ * threads within the same virtual machine. </p>
1085+ *
1086+ * @param position
1087+ * The position at which the locked region is to start; must be
1088+ * non-negative
1089+ *
1090+ * @param size
1091+ * The size of the locked region; must be non-negative, and the sum
1092+ * <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
1093+ *
1094+ * @param shared
1095+ * <tt>true</tt> to request a shared lock,
1096+ * <tt>false</tt> to request an exclusive lock
1097+ *
1098+ * @return A lock object representing the newly-acquired lock,
1099+ * or <tt>null</tt> if the lock could not be acquired
1100+ * because another program holds an overlapping lock
1101+ *
1102+ * @throws IllegalArgumentException
1103+ * If the preconditions on the parameters do not hold
1104+ *
1105+ * @throws ClosedChannelException
1106+ * If this channel is closed
1107+ *
1108+ * @throws OverlappingFileLockException
1109+ * If a lock that overlaps the requested region is already held by
1110+ * this Java virtual machine, or if another thread is already
1111+ * blocked in this method and is attempting to lock an overlapping
1112+ * region of the same file
1113+ *
1114+ * @throws IOException
1115+ * If some other I/O error occurs
1116+ *
1117+ * @see #lock()
1118+ * @see #lock(long,long,boolean)
1119+ * @see #tryLock()
1120+ */
1121+ public abstract FileLock tryLock(long position, long size, boolean shared)
1122+ throws IOException;
1123+
1124+ /**
1125+ * Attempts to acquire an exclusive lock on this channel's file.
1126+ *
1127+ * <p> An invocation of this method of the form <tt>fc.tryLock()</tt>
1128+ * behaves in exactly the same way as the invocation
1129+ *
1130+ * <pre>
1131+ * fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>
1132+ *
1133+ * @return A lock object representing the newly-acquired lock,
1134+ * or <tt>null</tt> if the lock could not be acquired
1135+ * because another program holds an overlapping lock
1136+ *
1137+ * @throws ClosedChannelException
1138+ * If this channel is closed
1139+ *
1140+ * @throws OverlappingFileLockException
1141+ * If a lock that overlaps the requested region is already held by
1142+ * this Java virtual machine, or if another thread is already
1143+ * blocked in this method and is attempting to lock an overlapping
1144+ * region
1145+ *
1146+ * @throws IOException
1147+ * If some other I/O error occurs
1148+ *
1149+ * @see #lock()
1150+ * @see #lock(long,long,boolean)
1151+ * @see #tryLock(long,long,boolean)
1152+ */
1153+ public final FileLock tryLock() throws IOException {
1154+ return tryLock(0L, Long.MAX_VALUE, false);
1155+ }
1156+
1157+}
java/pkg/java/nio/channels/FileLock.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/FileLock.java+326−0
@@ -0,0 +1,326 @@
1+/*
2+ * Copyright (c) 2001, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+
30+/**
31+ * A token representing a lock on a region of a file.
32+ *
33+ * <p> A file-lock object is created each time a lock is acquired on a file via
34+ * one of the {@link FileChannel#lock(long,long,boolean) lock} or {@link
35+ * FileChannel#tryLock(long,long,boolean) tryLock} methods of the
36+ * {@link FileChannel} class, or the {@link
37+ * AsynchronousFileChannel#lock(long,long,boolean,Object,CompletionHandler) lock}
38+ * or {@link AsynchronousFileChannel#tryLock(long,long,boolean) tryLock}
39+ * methods of the {@link AsynchronousFileChannel} class.
40+ *
41+ * <p> A file-lock object is initially valid. It remains valid until the lock
42+ * is released by invoking the {@link #release release} method, by closing the
43+ * channel that was used to acquire it, or by the termination of the Java
44+ * virtual machine, whichever comes first. The validity of a lock may be
45+ * tested by invoking its {@link #isValid isValid} method.
46+ *
47+ * <p> A file lock is either <i>exclusive</i> or <i>shared</i>. A shared lock
48+ * prevents other concurrently-running programs from acquiring an overlapping
49+ * exclusive lock, but does allow them to acquire overlapping shared locks. An
50+ * exclusive lock prevents other programs from acquiring an overlapping lock of
51+ * either type. Once it is released, a lock has no further effect on the locks
52+ * that may be acquired by other programs.
53+ *
54+ * <p> Whether a lock is exclusive or shared may be determined by invoking its
55+ * {@link #isShared isShared} method. Some platforms do not support shared
56+ * locks, in which case a request for a shared lock is automatically converted
57+ * into a request for an exclusive lock.
58+ *
59+ * <p> The locks held on a particular file by a single Java virtual machine do
60+ * not overlap. The {@link #overlaps overlaps} method may be used to test
61+ * whether a candidate lock range overlaps an existing lock.
62+ *
63+ * <p> A file-lock object records the file channel upon whose file the lock is
64+ * held, the type and validity of the lock, and the position and size of the
65+ * locked region. Only the validity of a lock is subject to change over time;
66+ * all other aspects of a lock's state are immutable.
67+ *
68+ * <p> File locks are held on behalf of the entire Java virtual machine.
69+ * They are not suitable for controlling access to a file by multiple
70+ * threads within the same virtual machine.
71+ *
72+ * <p> File-lock objects are safe for use by multiple concurrent threads.
73+ *
74+ *
75+ * <a name="pdep"><h4> Platform dependencies </h4></a>
76+ *
77+ * <p> This file-locking API is intended to map directly to the native locking
78+ * facility of the underlying operating system. Thus the locks held on a file
79+ * should be visible to all programs that have access to the file, regardless
80+ * of the language in which those programs are written.
81+ *
82+ * <p> Whether or not a lock actually prevents another program from accessing
83+ * the content of the locked region is system-dependent and therefore
84+ * unspecified. The native file-locking facilities of some systems are merely
85+ * <i>advisory</i>, meaning that programs must cooperatively observe a known
86+ * locking protocol in order to guarantee data integrity. On other systems
87+ * native file locks are <i>mandatory</i>, meaning that if one program locks a
88+ * region of a file then other programs are actually prevented from accessing
89+ * that region in a way that would violate the lock. On yet other systems,
90+ * whether native file locks are advisory or mandatory is configurable on a
91+ * per-file basis. To ensure consistent and correct behavior across platforms,
92+ * it is strongly recommended that the locks provided by this API be used as if
93+ * they were advisory locks.
94+ *
95+ * <p> On some systems, acquiring a mandatory lock on a region of a file
96+ * prevents that region from being {@link java.nio.channels.FileChannel#map
97+ * <i>mapped into memory</i>}, and vice versa. Programs that combine
98+ * locking and mapping should be prepared for this combination to fail.
99+ *
100+ * <p> On some systems, closing a channel releases all locks held by the Java
101+ * virtual machine on the underlying file regardless of whether the locks were
102+ * acquired via that channel or via another channel open on the same file. It
103+ * is strongly recommended that, within a program, a unique channel be used to
104+ * acquire all locks on any given file.
105+ *
106+ * <p> Some network filesystems permit file locking to be used with
107+ * memory-mapped files only when the locked regions are page-aligned and a
108+ * whole multiple of the underlying hardware's page size. Some network
109+ * filesystems do not implement file locks on regions that extend past a
110+ * certain position, often 2<sup>30</sup> or 2<sup>31</sup>. In general, great
111+ * care should be taken when locking files that reside on network filesystems.
112+ *
113+ *
114+ * @author Mark Reinhold
115+ * @author JSR-51 Expert Group
116+ * @since 1.4
117+ */
118+
119+public abstract class FileLock implements AutoCloseable {
120+
121+ private final Channel channel;
122+ private final long position;
123+ private final long size;
124+ private final boolean shared;
125+
126+ /**
127+ * Initializes a new instance of this class. </p>
128+ *
129+ * @param channel
130+ * The file channel upon whose file this lock is held
131+ *
132+ * @param position
133+ * The position within the file at which the locked region starts;
134+ * must be non-negative
135+ *
136+ * @param size
137+ * The size of the locked region; must be non-negative, and the sum
138+ * <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
139+ *
140+ * @param shared
141+ * <tt>true</tt> if this lock is shared,
142+ * <tt>false</tt> if it is exclusive
143+ *
144+ * @throws IllegalArgumentException
145+ * If the preconditions on the parameters do not hold
146+ */
147+ protected FileLock(FileChannel channel,
148+ long position, long size, boolean shared)
149+ {
150+ if (position < 0)
151+ throw new IllegalArgumentException("Negative position");
152+ if (size < 0)
153+ throw new IllegalArgumentException("Negative size");
154+ if (position + size < 0)
155+ throw new IllegalArgumentException("Negative position + size");
156+ this.channel = channel;
157+ this.position = position;
158+ this.size = size;
159+ this.shared = shared;
160+ }
161+
162+ /**
163+ * Initializes a new instance of this class.
164+ *
165+ * @param channel
166+ * The channel upon whose file this lock is held
167+ *
168+ * @param position
169+ * The position within the file at which the locked region starts;
170+ * must be non-negative
171+ *
172+ * @param size
173+ * The size of the locked region; must be non-negative, and the sum
174+ * <tt>position</tt>&nbsp;+&nbsp;<tt>size</tt> must be non-negative
175+ *
176+ * @param shared
177+ * <tt>true</tt> if this lock is shared,
178+ * <tt>false</tt> if it is exclusive
179+ *
180+ * @throws IllegalArgumentException
181+ * If the preconditions on the parameters do not hold
182+ *
183+ * @since 1.7
184+ */
185+ protected FileLock(AsynchronousFileChannel channel,
186+ long position, long size, boolean shared)
187+ {
188+ if (position < 0)
189+ throw new IllegalArgumentException("Negative position");
190+ if (size < 0)
191+ throw new IllegalArgumentException("Negative size");
192+ if (position + size < 0)
193+ throw new IllegalArgumentException("Negative position + size");
194+ this.channel = channel;
195+ this.position = position;
196+ this.size = size;
197+ this.shared = shared;
198+ }
199+
200+ /**
201+ * Returns the file channel upon whose file this lock was acquired.
202+ *
203+ * <p> This method has been superseded by the {@link #acquiredBy acquiredBy}
204+ * method.
205+ *
206+ * @return The file channel, or {@code null} if the file lock was not
207+ * acquired by a file channel.
208+ */
209+ public final FileChannel channel() {
210+ return (channel instanceof FileChannel) ? (FileChannel)channel : null;
211+ }
212+
213+ /**
214+ * Returns the channel upon whose file this lock was acquired.
215+ *
216+ * @return The channel upon whose file this lock was acquired.
217+ *
218+ * @since 1.7
219+ */
220+ public Channel acquiredBy() {
221+ return channel;
222+ }
223+
224+ /**
225+ * Returns the position within the file of the first byte of the locked
226+ * region.
227+ *
228+ * <p> A locked region need not be contained within, or even overlap, the
229+ * actual underlying file, so the value returned by this method may exceed
230+ * the file's current size. </p>
231+ *
232+ * @return The position
233+ */
234+ public final long position() {
235+ return position;
236+ }
237+
238+ /**
239+ * Returns the size of the locked region in bytes.
240+ *
241+ * <p> A locked region need not be contained within, or even overlap, the
242+ * actual underlying file, so the value returned by this method may exceed
243+ * the file's current size. </p>
244+ *
245+ * @return The size of the locked region
246+ */
247+ public final long size() {
248+ return size;
249+ }
250+
251+ /**
252+ * Tells whether this lock is shared. </p>
253+ *
254+ * @return <tt>true</tt> if lock is shared,
255+ * <tt>false</tt> if it is exclusive
256+ */
257+ public final boolean isShared() {
258+ return shared;
259+ }
260+
261+ /**
262+ * Tells whether or not this lock overlaps the given lock range. </p>
263+ *
264+ * @return <tt>true</tt> if, and only if, this lock and the given lock
265+ * range overlap by at least one byte
266+ */
267+ public final boolean overlaps(long position, long size) {
268+ if (position + size <= this.position)
269+ return false; // That is below this
270+ if (this.position + this.size <= position)
271+ return false; // This is below that
272+ return true;
273+ }
274+
275+ /**
276+ * Tells whether or not this lock is valid.
277+ *
278+ * <p> A lock object remains valid until it is released or the associated
279+ * file channel is closed, whichever comes first. </p>
280+ *
281+ * @return <tt>true</tt> if, and only if, this lock is valid
282+ */
283+ public abstract boolean isValid();
284+
285+ /**
286+ * Releases this lock.
287+ *
288+ * <p> If this lock object is valid then invoking this method releases the
289+ * lock and renders the object invalid. If this lock object is invalid
290+ * then invoking this method has no effect. </p>
291+ *
292+ * @throws ClosedChannelException
293+ * If the channel that was used to acquire this lock
294+ * is no longer open
295+ *
296+ * @throws IOException
297+ * If an I/O error occurs
298+ */
299+ public abstract void release() throws IOException;
300+
301+ /**
302+ * This method invokes the {@link #release} method. It was added
303+ * to the class so that it could be used in conjunction with the
304+ * automatic resource management block construct.
305+ *
306+ * @since 1.7
307+ */
308+ public final void close() throws IOException {
309+ release();
310+ }
311+
312+ /**
313+ * Returns a string describing the range, type, and validity of this lock.
314+ *
315+ * @return A descriptive string
316+ */
317+ public final String toString() {
318+ return (this.getClass().getName()
319+ + "[" + position
320+ + ":" + size
321+ + " " + (shared ? "shared" : "exclusive")
322+ + " " + (isValid() ? "valid" : "invalid")
323+ + "]");
324+ }
325+
326+}
java/pkg/java/nio/channels/GatheringByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/GatheringByteChannel.java+166−0
@@ -0,0 +1,166 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.ByteBuffer;
30+
31+
32+/**
33+ * A channel that can write bytes from a sequence of buffers.
34+ *
35+ * <p> A <i>gathering</i> write operation writes, in a single invocation, a
36+ * sequence of bytes from one or more of a given sequence of buffers.
37+ * Gathering writes are often useful when implementing network protocols or
38+ * file formats that, for example, group data into segments consisting of one
39+ * or more fixed-length headers followed by a variable-length body. Similar
40+ * <i>scattering</i> read operations are defined in the {@link
41+ * ScatteringByteChannel} interface. </p>
42+ *
43+ *
44+ * @author Mark Reinhold
45+ * @author JSR-51 Expert Group
46+ * @since 1.4
47+ */
48+
49+public interface GatheringByteChannel
50+ extends WritableByteChannel
51+{
52+
53+ /**
54+ * Writes a sequence of bytes to this channel from a subsequence of the
55+ * given buffers.
56+ *
57+ * <p> An attempt is made to write up to <i>r</i> bytes to this channel,
58+ * where <i>r</i> is the total number of bytes remaining in the specified
59+ * subsequence of the given buffer array, that is,
60+ *
61+ * <blockquote><pre>
62+ * srcs[offset].remaining()
63+ * + srcs[offset+1].remaining()
64+ * + ... + srcs[offset+length-1].remaining()</pre></blockquote>
65+ *
66+ * at the moment that this method is invoked.
67+ *
68+ * <p> Suppose that a byte sequence of length <i>n</i> is written, where
69+ * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
70+ * Up to the first <tt>srcs[offset].remaining()</tt> bytes of this sequence
71+ * are written from buffer <tt>srcs[offset]</tt>, up to the next
72+ * <tt>srcs[offset+1].remaining()</tt> bytes are written from buffer
73+ * <tt>srcs[offset+1]</tt>, and so forth, until the entire byte sequence is
74+ * written. As many bytes as possible are written from each buffer, hence
75+ * the final position of each updated buffer, except the last updated
76+ * buffer, is guaranteed to be equal to that buffer's limit.
77+ *
78+ * <p> Unless otherwise specified, a write operation will return only after
79+ * writing all of the <i>r</i> requested bytes. Some types of channels,
80+ * depending upon their state, may write only some of the bytes or possibly
81+ * none at all. A socket channel in non-blocking mode, for example, cannot
82+ * write any more bytes than are free in the socket's output buffer.
83+ *
84+ * <p> This method may be invoked at any time. If another thread has
85+ * already initiated a write operation upon this channel, however, then an
86+ * invocation of this method will block until the first operation is
87+ * complete. </p>
88+ *
89+ * @param srcs
90+ * The buffers from which bytes are to be retrieved
91+ *
92+ * @param offset
93+ * The offset within the buffer array of the first buffer from
94+ * which bytes are to be retrieved; must be non-negative and no
95+ * larger than <tt>srcs.length</tt>
96+ *
97+ * @param length
98+ * The maximum number of buffers to be accessed; must be
99+ * non-negative and no larger than
100+ * <tt>srcs.length</tt>&nbsp;-&nbsp;<tt>offset</tt>
101+ *
102+ * @return The number of bytes written, possibly zero
103+ *
104+ * @throws IndexOutOfBoundsException
105+ * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
106+ * parameters do not hold
107+ *
108+ * @throws NonWritableChannelException
109+ * If this channel was not opened for writing
110+ *
111+ * @throws ClosedChannelException
112+ * If this channel is closed
113+ *
114+ * @throws AsynchronousCloseException
115+ * If another thread closes this channel
116+ * while the write operation is in progress
117+ *
118+ * @throws ClosedByInterruptException
119+ * If another thread interrupts the current thread
120+ * while the write operation is in progress, thereby
121+ * closing the channel and setting the current thread's
122+ * interrupt status
123+ *
124+ * @throws IOException
125+ * If some other I/O error occurs
126+ */
127+ public long write(ByteBuffer[] srcs, int offset, int length)
128+ throws IOException;
129+
130+
131+ /**
132+ * Writes a sequence of bytes to this channel from the given buffers.
133+ *
134+ * <p> An invocation of this method of the form <tt>c.write(srcs)</tt>
135+ * behaves in exactly the same manner as the invocation
136+ *
137+ * <blockquote><pre>
138+ * c.write(srcs, 0, srcs.length);</pre></blockquote>
139+ *
140+ * @param srcs
141+ * The buffers from which bytes are to be retrieved
142+ *
143+ * @return The number of bytes written, possibly zero
144+ *
145+ * @throws NonWritableChannelException
146+ * If this channel was not opened for writing
147+ *
148+ * @throws ClosedChannelException
149+ * If this channel is closed
150+ *
151+ * @throws AsynchronousCloseException
152+ * If another thread closes this channel
153+ * while the write operation is in progress
154+ *
155+ * @throws ClosedByInterruptException
156+ * If another thread interrupts the current thread
157+ * while the write operation is in progress, thereby
158+ * closing the channel and setting the current thread's
159+ * interrupt status
160+ *
161+ * @throws IOException
162+ * If some other I/O error occurs
163+ */
164+ public long write(ByteBuffer[] srcs) throws IOException;
165+
166+}
java/pkg/java/nio/channels/InterruptibleChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/InterruptibleChannel.java+82−0
@@ -0,0 +1,82 @@
1+/*
2+ * Copyright (c) 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+/*
27+ */
28+
29+package java.nio.channels;
30+
31+import java.io.IOException;
32+
33+
34+/**
35+ * A channel that can be asynchronously closed and interrupted.
36+ *
37+ * <p> A channel that implements this interface is <i>asynchronously
38+ * closeable:</i> If a thread is blocked in an I/O operation on an
39+ * interruptible channel then another thread may invoke the channel's {@link
40+ * #close close} method. This will cause the blocked thread to receive an
41+ * {@link AsynchronousCloseException}.
42+ *
43+ * <p> A channel that implements this interface is also <i>interruptible:</i>
44+ * If a thread is blocked in an I/O operation on an interruptible channel then
45+ * another thread may invoke the blocked thread's {@link Thread#interrupt()
46+ * interrupt} method. This will cause the channel to be closed, the blocked
47+ * thread to receive a {@link ClosedByInterruptException}, and the blocked
48+ * thread's interrupt status to be set.
49+ *
50+ * <p> If a thread's interrupt status is already set and it invokes a blocking
51+ * I/O operation upon a channel then the channel will be closed and the thread
52+ * will immediately receive a {@link ClosedByInterruptException}; its interrupt
53+ * status will remain set.
54+ *
55+ * <p> A channel supports asynchronous closing and interruption if, and only
56+ * if, it implements this interface. This can be tested at runtime, if
57+ * necessary, via the <tt>instanceof</tt> operator.
58+ *
59+ *
60+ * @author Mark Reinhold
61+ * @author JSR-51 Expert Group
62+ * @since 1.4
63+ */
64+
65+public interface InterruptibleChannel
66+ extends Channel
67+{
68+
69+ /**
70+ * Closes this channel.
71+ *
72+ * <p> Any thread currently blocked in an I/O operation upon this channel
73+ * will receive an {@link AsynchronousCloseException}.
74+ *
75+ * <p> This method otherwise behaves exactly as specified by the {@link
76+ * Channel#close Channel} interface. </p>
77+ *
78+ * @throws IOException If an I/O error occurs
79+ */
80+ public void close() throws IOException;
81+
82+}
java/pkg/java/nio/channels/MembershipKey.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/MembershipKey.java+177−0
@@ -0,0 +1,177 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.net.InetAddress;
29+import java.net.NetworkInterface;
30+import java.io.IOException;
31+
32+/**
33+ * A token representing the membership of an Internet Protocol (IP) multicast
34+ * group.
35+ *
36+ * <p> A membership key may represent a membership to receive all datagrams sent
37+ * to the group, or it may be <em>source-specific</em>, meaning that it
38+ * represents a membership that receives only datagrams from a specific source
39+ * address. Whether or not a membership key is source-specific may be determined
40+ * by invoking its {@link #sourceAddress() sourceAddress} method.
41+ *
42+ * <p> A membership key is valid upon creation and remains valid until the
43+ * membership is dropped by invoking the {@link #drop() drop} method, or
44+ * the channel is closed. The validity of the membership key may be tested
45+ * by invoking its {@link #isValid() isValid} method.
46+ *
47+ * <p> Where a membership key is not source-specific and the underlying operation
48+ * system supports source filtering, then the {@link #block block} and {@link
49+ * #unblock unblock} methods can be used to block or unblock multicast datagrams
50+ * from particular source addresses.
51+ *
52+ * @see MulticastChannel
53+ *
54+ * @since 1.7
55+ */
56+public abstract class MembershipKey {
57+
58+ /**
59+ * Initializes a new instance of this class.
60+ */
61+ protected MembershipKey() {
62+ }
63+
64+ /**
65+ * Tells whether or not this membership is valid.
66+ *
67+ * <p> A multicast group membership is valid upon creation and remains
68+ * valid until the membership is dropped by invoking the {@link #drop() drop}
69+ * method, or the channel is closed.
70+ *
71+ * @return {@code true} if this membership key is valid, {@code false}
72+ * otherwise
73+ */
74+ public abstract boolean isValid();
75+
76+ /**
77+ * Drop membership.
78+ *
79+ * <p> If the membership key represents a membership to receive all datagrams
80+ * then the membership is dropped and the channel will no longer receive any
81+ * datagrams sent to the group. If the membership key is source-specific
82+ * then the channel will no longer receive datagrams sent to the group from
83+ * that source address.
84+ *
85+ * <p> After membership is dropped it may still be possible to receive
86+ * datagrams sent to the group. This can arise when datagrams are waiting to
87+ * be received in the socket's receive buffer. After membership is dropped
88+ * then the channel may {@link MulticastChannel#join join} the group again
89+ * in which case a new membership key is returned.
90+ *
91+ * <p> Upon return, this membership object will be {@link #isValid() invalid}.
92+ * If the multicast group membership is already invalid then invoking this
93+ * method has no effect. Once a multicast group membership is invalid,
94+ * it remains invalid forever.
95+ */
96+ public abstract void drop();
97+
98+ /**
99+ * Block multicast datagrams from the given source address.
100+ *
101+ * <p> If this membership key is not source-specific, and the underlying
102+ * operating system supports source filtering, then this method blocks
103+ * multicast datagrams from the given source address. If the given source
104+ * address is already blocked then this method has no effect.
105+ * After a source address is blocked it may still be possible to receive
106+ * datagams from that source. This can arise when datagrams are waiting to
107+ * be received in the socket's receive buffer.
108+ *
109+ * @param source
110+ * The source address to block
111+ *
112+ * @return This membership key
113+ *
114+ * @throws IllegalArgumentException
115+ * If the {@code source} parameter is not a unicast address or
116+ * is not the same address type as the multicast group
117+ * @throws IllegalStateException
118+ * If this membership key is source-specific or is no longer valid
119+ * @throws UnsupportedOperationException
120+ * If the underlying operating system does not support source
121+ * filtering
122+ * @throws IOException
123+ * If an I/O error occurs
124+ */
125+ public abstract MembershipKey block(InetAddress source) throws IOException;
126+
127+ /**
128+ * Unblock multicast datagrams from the given source address that was
129+ * previously blocked using the {@link #block(InetAddress) block} method.
130+ *
131+ * @param source
132+ * The source address to unblock
133+ *
134+ * @return This membership key
135+ *
136+ * @throws IllegalStateException
137+ * If the given source address is not currently blocked or the
138+ * membership key is no longer valid
139+ */
140+ public abstract MembershipKey unblock(InetAddress source);
141+
142+ /**
143+ * Returns the channel for which this membership key was created. This
144+ * method will continue to return the channel even after the membership
145+ * becomes {@link #isValid invalid}.
146+ *
147+ * @return the channel
148+ */
149+ public abstract MulticastChannel channel();
150+
151+ /**
152+ * Returns the multicast group for which this membership key was created.
153+ * This method will continue to return the group even after the membership
154+ * becomes {@link #isValid invalid}.
155+ *
156+ * @return the multicast group
157+ */
158+ public abstract InetAddress group();
159+
160+ /**
161+ * Returns the network interface for which this membership key was created.
162+ * This method will continue to return the network interface even after the
163+ * membership becomes {@link #isValid invalid}.
164+ *
165+ * @return the network interface
166+ */
167+ public abstract NetworkInterface networkInterface();
168+
169+ /**
170+ * Returns the source address if this membership key is source-specific,
171+ * or {@code null} if this membership is not source-specific.
172+ *
173+ * @return The source address if this membership key is source-specific,
174+ * otherwise {@code null}
175+ */
176+ public abstract InetAddress sourceAddress();
177+}
java/pkg/java/nio/channels/MulticastChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/MulticastChannel.java+230−0
@@ -0,0 +1,230 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.net.InetAddress;
29+import java.net.NetworkInterface;
30+import java.io.IOException;
31+import java.net.ProtocolFamily; // javadoc
32+import java.net.StandardProtocolFamily; // javadoc
33+import java.net.StandardSocketOptions; // javadoc
34+
35+/**
36+ * A network channel that supports Internet Protocol (IP) multicasting.
37+ *
38+ * <p> IP multicasting is the transmission of IP datagrams to members of
39+ * a <em>group</em> that is zero or more hosts identified by a single destination
40+ * address.
41+ *
42+ * <p> In the case of a channel to an {@link StandardProtocolFamily#INET IPv4} socket,
43+ * the underlying operating system supports <a href="http://www.ietf.org/rfc/rfc2236.txt">
44+ * <i>RFC&nbsp;2236: Internet Group Management Protocol, Version 2 (IGMPv2)</i></a>.
45+ * It may optionally support source filtering as specified by <a
46+ * href="http://www.ietf.org/rfc/rfc3376.txt"> <i>RFC&nbsp;3376: Internet Group
47+ * Management Protocol, Version 3 (IGMPv3)</i></a>.
48+ * For channels to an {@link StandardProtocolFamily#INET6 IPv6} socket, the equivalent
49+ * standards are <a href="http://www.ietf.org/rfc/rfc2710.txt"> <i>RFC&nbsp;2710:
50+ * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a
51+ * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC&nbsp;3810: Multicast Listener
52+ * Discovery Version 2 (MLDv2) for IPv6</i></a>.
53+ *
54+ * <p> The {@link #join(InetAddress,NetworkInterface)} method is used to
55+ * join a group and receive all multicast datagrams sent to the group. A channel
56+ * may join several multicast groups and may join the same group on several
57+ * {@link NetworkInterface interfaces}. Membership is dropped by invoking the {@link
58+ * MembershipKey#drop drop} method on the returned {@link MembershipKey}. If the
59+ * underlying platform supports source filtering then the {@link MembershipKey#block
60+ * block} and {@link MembershipKey#unblock unblock} methods can be used to block or
61+ * unblock multicast datagrams from particular source addresses.
62+ *
63+ * <p> The {@link #join(InetAddress,NetworkInterface,InetAddress)} method
64+ * is used to begin receiving datagrams sent to a group whose source address matches
65+ * a given source address. This method throws {@link UnsupportedOperationException}
66+ * if the underlying platform does not support source filtering. Membership is
67+ * <em>cumulative</em> and this method may be invoked again with the same group
68+ * and interface to allow receiving datagrams from other source addresses. The
69+ * method returns a {@link MembershipKey} that represents membership to receive
70+ * datagrams from the given source address. Invoking the key's {@link
71+ * MembershipKey#drop drop} method drops membership so that datagrams from the
72+ * source address can no longer be received.
73+ *
74+ * <h4>Platform dependencies</h4>
75+ *
76+ * The multicast implementation is intended to map directly to the native
77+ * multicasting facility. Consequently, the following items should be considered
78+ * when developing an application that receives IP multicast datagrams:
79+ *
80+ * <ol>
81+ *
82+ * <li><p> The creation of the channel should specify the {@link ProtocolFamily}
83+ * that corresponds to the address type of the multicast groups that the channel
84+ * will join. There is no guarantee that a channel to a socket in one protocol
85+ * family can join and receive multicast datagrams when the address of the
86+ * multicast group corresponds to another protocol family. For example, it is
87+ * implementation specific if a channel to an {@link StandardProtocolFamily#INET6 IPv6}
88+ * socket can join an {@link StandardProtocolFamily#INET IPv4} multicast group and receive
89+ * multicast datagrams sent to the group. </p></li>
90+ *
91+ * <li><p> The channel's socket should be bound to the {@link
92+ * InetAddress#isAnyLocalAddress wildcard} address. If the socket is bound to
93+ * a specific address, rather than the wildcard address then it is implementation
94+ * specific if multicast datagrams are received by the socket. </p></li>
95+ *
96+ * <li><p> The {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} option should be
97+ * enabled prior to {@link NetworkChannel#bind binding} the socket. This is
98+ * required to allow multiple members of the group to bind to the same
99+ * address. </p></li>
100+ *
101+ * </ol>
102+ *
103+ * <p> <b>Usage Example:</b>
104+ * <pre>
105+ * // join multicast group on this interface, and also use this
106+ * // interface for outgoing multicast datagrams
107+ * NetworkInterface ni = NetworkInterface.getByName("hme0");
108+ *
109+ * DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
110+ * .setOption(StandardSocketOptions.SO_REUSEADDR, true)
111+ * .bind(new InetSocketAddress(5000))
112+ * .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);
113+ *
114+ * InetAddress group = InetAddress.getByName("225.4.5.6");
115+ *
116+ * MembershipKey key = dc.join(group, ni);
117+ * </pre>
118+ *
119+ * @since 1.7
120+ */
121+
122+public interface MulticastChannel
123+ extends NetworkChannel
124+{
125+ /**
126+ * Closes this channel.
127+ *
128+ * <p> If the channel is a member of a multicast group then the membership
129+ * is {@link MembershipKey#drop dropped}. Upon return, the {@link
130+ * MembershipKey membership-key} will be {@link MembershipKey#isValid
131+ * invalid}.
132+ *
133+ * <p> This method otherwise behaves exactly as specified by the {@link
134+ * Channel} interface.
135+ *
136+ * @throws IOException
137+ * If an I/O error occurs
138+ */
139+ @Override void close() throws IOException;
140+
141+ /**
142+ * Joins a multicast group to begin receiving all datagrams sent to the group,
143+ * returning a membership key.
144+ *
145+ * <p> If this channel is currently a member of the group on the given
146+ * interface to receive all datagrams then the membership key, representing
147+ * that membership, is returned. Otherwise this channel joins the group and
148+ * the resulting new membership key is returned. The resulting membership key
149+ * is not {@link MembershipKey#sourceAddress source-specific}.
150+ *
151+ * <p> A multicast channel may join several multicast groups, including
152+ * the same group on more than one interface. An implementation may impose a
153+ * limit on the number of groups that may be joined at the same time.
154+ *
155+ * @param group
156+ * The multicast address to join
157+ * @param interf
158+ * The network interface on which to join the group
159+ *
160+ * @return The membership key
161+ *
162+ * @throws IllegalArgumentException
163+ * If the group parameter is not a {@link InetAddress#isMulticastAddress
164+ * multicast} address, or the group parameter is an address type
165+ * that is not supported by this channel
166+ * @throws IllegalStateException
167+ * If the channel already has source-specific membership of the
168+ * group on the interface
169+ * @throws UnsupportedOperationException
170+ * If the channel's socket is not an Internet Protocol socket
171+ * @throws ClosedChannelException
172+ * If this channel is closed
173+ * @throws IOException
174+ * If an I/O error occurs
175+ * @throws SecurityException
176+ * If a security manager is set, and its
177+ * {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
178+ * method denies access to the multiast group
179+ */
180+ MembershipKey join(InetAddress group, NetworkInterface interf)
181+ throws IOException;
182+
183+ /**
184+ * Joins a multicast group to begin receiving datagrams sent to the group
185+ * from a given source address.
186+ *
187+ * <p> If this channel is currently a member of the group on the given
188+ * interface to receive datagrams from the given source address then the
189+ * membership key, representing that membership, is returned. Otherwise this
190+ * channel joins the group and the resulting new membership key is returned.
191+ * The resulting membership key is {@link MembershipKey#sourceAddress
192+ * source-specific}.
193+ *
194+ * <p> Membership is <em>cumulative</em> and this method may be invoked
195+ * again with the same group and interface to allow receiving datagrams sent
196+ * by other source addresses to the group.
197+ *
198+ * @param group
199+ * The multicast address to join
200+ * @param interf
201+ * The network interface on which to join the group
202+ * @param source
203+ * The source address
204+ *
205+ * @return The membership key
206+ *
207+ * @throws IllegalArgumentException
208+ * If the group parameter is not a {@link
209+ * InetAddress#isMulticastAddress multicast} address, the
210+ * source parameter is not a unicast address, the group
211+ * parameter is an address type that is not supported by this channel,
212+ * or the source parameter is not the same address type as the group
213+ * @throws IllegalStateException
214+ * If the channel is currently a member of the group on the given
215+ * interface to receive all datagrams
216+ * @throws UnsupportedOperationException
217+ * If the channel's socket is not an Internet Protocol socket or
218+ * source filtering is not supported
219+ * @throws ClosedChannelException
220+ * If this channel is closed
221+ * @throws IOException
222+ * If an I/O error occurs
223+ * @throws SecurityException
224+ * If a security manager is set, and its
225+ * {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
226+ * method denies access to the multiast group
227+ */
228+ MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source)
229+ throws IOException;
230+}
java/pkg/java/nio/channels/NetworkChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/NetworkChannel.java+160−0
@@ -0,0 +1,160 @@
1+/*
2+ * Copyright (c) 2007, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.net.SocketOption;
29+import java.net.SocketAddress;
30+import java.util.Set;
31+import java.io.IOException;
32+
33+/**
34+ * A channel to a network socket.
35+ *
36+ * <p> A channel that implements this interface is a channel to a network
37+ * socket. The {@link #bind(SocketAddress) bind} method is used to bind the
38+ * socket to a local {@link SocketAddress address}, the {@link #getLocalAddress()
39+ * getLocalAddress} method returns the address that the socket is bound to, and
40+ * the {@link #setOption(SocketOption,Object) setOption} and {@link
41+ * #getOption(SocketOption) getOption} methods are used to set and query socket
42+ * options. An implementation of this interface should specify the socket options
43+ * that it supports.
44+ *
45+ * <p> The {@link #bind bind} and {@link #setOption setOption} methods that do
46+ * not otherwise have a value to return are specified to return the network
47+ * channel upon which they are invoked. This allows method invocations to be
48+ * chained. Implementations of this interface should specialize the return type
49+ * so that method invocations on the implementation class can be chained.
50+ *
51+ * @since 1.7
52+ */
53+
54+public interface NetworkChannel
55+ extends Channel
56+{
57+ /**
58+ * Binds the channel's socket to a local address.
59+ *
60+ * <p> This method is used to establish an association between the socket and
61+ * a local address. Once an association is established then the socket remains
62+ * bound until the channel is closed. If the {@code local} parameter has the
63+ * value {@code null} then the socket will be bound to an address that is
64+ * assigned automatically.
65+ *
66+ * @param local
67+ * The address to bind the socket, or {@code null} to bind the socket
68+ * to an automatically assigned socket address
69+ *
70+ * @return This channel
71+ *
72+ * @throws AlreadyBoundException
73+ * If the socket is already bound
74+ * @throws UnsupportedAddressTypeException
75+ * If the type of the given address is not supported
76+ * @throws ClosedChannelException
77+ * If the channel is closed
78+ * @throws IOException
79+ * If some other I/O error occurs
80+ * @throws SecurityException
81+ * If a security manager is installed and it denies an unspecified
82+ * permission. An implementation of this interface should specify
83+ * any required permissions.
84+ *
85+ * @see #getLocalAddress
86+ */
87+ NetworkChannel bind(SocketAddress local) throws IOException;
88+
89+ /**
90+ * Returns the socket address that this channel's socket is bound to, or
91+ * {@code null} if the socket is not bound.
92+ *
93+ * <p> Where the channel is {@link #bind bound} to an Internet Protocol
94+ * socket address then the return value from this method is of type {@link
95+ * java.net.InetSocketAddress}.
96+ *
97+ * @return The socket address that the socket is bound to, or {@code null}
98+ * if the channel's socket is not bound
99+ *
100+ * @throws ClosedChannelException
101+ * If the channel is closed
102+ * @throws IOException
103+ * If an I/O error occurs
104+ */
105+ SocketAddress getLocalAddress() throws IOException;
106+
107+ /**
108+ * Sets the value of a socket option.
109+ *
110+ * @param name
111+ * The socket option
112+ * @param value
113+ * The value of the socket option. A value of {@code null} may be
114+ * a valid value for some socket options.
115+ *
116+ * @return This channel
117+ *
118+ * @throws UnsupportedOperationException
119+ * If the socket option is not supported by this channel
120+ * @throws IllegalArgumentException
121+ * If the value is not a valid value for this socket option
122+ * @throws ClosedChannelException
123+ * If this channel is closed
124+ * @throws IOException
125+ * If an I/O error occurs
126+ *
127+ * @see java.net.StandardSocketOptions
128+ */
129+ <T> NetworkChannel setOption(SocketOption<T> name, T value) throws IOException;
130+
131+ /**
132+ * Returns the value of a socket option.
133+ *
134+ * @param name
135+ * The socket option
136+ *
137+ * @return The value of the socket option. A value of {@code null} may be
138+ * a valid value for some socket options.
139+ *
140+ * @throws UnsupportedOperationException
141+ * If the socket option is not supported by this channel
142+ * @throws ClosedChannelException
143+ * If this channel is closed
144+ * @throws IOException
145+ * If an I/O error occurs
146+ *
147+ * @see java.net.StandardSocketOptions
148+ */
149+ <T> T getOption(SocketOption<T> name) throws IOException;
150+
151+ /**
152+ * Returns a set of the socket options supported by this channel.
153+ *
154+ * <p> This method will continue to return the set of options even after the
155+ * channel has been closed.
156+ *
157+ * @return A set of the socket options supported by this channel
158+ */
159+ Set<SocketOption<?>> supportedOptions();
160+}
java/pkg/java/nio/channels/Pipe$SinkChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Pipe$SourceChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Pipe.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Pipe.java+153−0
@@ -0,0 +1,153 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.channels.spi.*;
30+
31+
32+/**
33+ * A pair of channels that implements a unidirectional pipe.
34+ *
35+ * <p> A pipe consists of a pair of channels: A writable {@link
36+ * Pipe.SinkChannel </code>sink<code>} channel and a readable {@link
37+ * Pipe.SourceChannel </code>source<code>} channel. Once some bytes are
38+ * written to the sink channel they can be read from source channel in exactly
39+ * the order in which they were written.
40+ *
41+ * <p> Whether or not a thread writing bytes to a pipe will block until another
42+ * thread reads those bytes, or some previously-written bytes, from the pipe is
43+ * system-dependent and therefore unspecified. Many pipe implementations will
44+ * buffer up to a certain number of bytes between the sink and source channels,
45+ * but such buffering should not be assumed. </p>
46+ *
47+ *
48+ * @author Mark Reinhold
49+ * @author JSR-51 Expert Group
50+ * @since 1.4
51+ */
52+
53+public abstract class Pipe {
54+
55+ /**
56+ * A channel representing the readable end of a {@link Pipe}. </p>
57+ *
58+ * @since 1.4
59+ */
60+ public static abstract class SourceChannel
61+ extends AbstractSelectableChannel
62+ implements ReadableByteChannel, ScatteringByteChannel
63+ {
64+ /**
65+ * Constructs a new instance of this class.
66+ */
67+ protected SourceChannel(SelectorProvider provider) {
68+ super(provider);
69+ }
70+
71+ /**
72+ * Returns an operation set identifying this channel's supported
73+ * operations.
74+ *
75+ * <p> Pipe-source channels only support reading, so this method
76+ * returns {@link SelectionKey#OP_READ}. </p>
77+ *
78+ * @return The valid-operation set
79+ */
80+ public final int validOps() {
81+ return SelectionKey.OP_READ;
82+ }
83+
84+ }
85+
86+ /**
87+ * A channel representing the writable end of a {@link Pipe}. </p>
88+ *
89+ * @since 1.4
90+ */
91+ public static abstract class SinkChannel
92+ extends AbstractSelectableChannel
93+ implements WritableByteChannel, GatheringByteChannel
94+ {
95+ /**
96+ * Initializes a new instance of this class.
97+ */
98+ protected SinkChannel(SelectorProvider provider) {
99+ super(provider);
100+ }
101+
102+ /**
103+ * Returns an operation set identifying this channel's supported
104+ * operations.
105+ *
106+ * <p> Pipe-sink channels only support writing, so this method returns
107+ * {@link SelectionKey#OP_WRITE}. </p>
108+ *
109+ * @return The valid-operation set
110+ */
111+ public final int validOps() {
112+ return SelectionKey.OP_WRITE;
113+ }
114+
115+ }
116+
117+ /**
118+ * Initializes a new instance of this class.
119+ */
120+ protected Pipe() { }
121+
122+ /**
123+ * Returns this pipe's source channel. </p>
124+ *
125+ * @return This pipe's source channel
126+ */
127+ public abstract SourceChannel source();
128+
129+ /**
130+ * Returns this pipe's sink channel. </p>
131+ *
132+ * @return This pipe's sink channel
133+ */
134+ public abstract SinkChannel sink();
135+
136+ /**
137+ * Opens a pipe.
138+ *
139+ * <p> The new pipe is created by invoking the {@link
140+ * java.nio.channels.spi.SelectorProvider#openPipe openPipe} method of the
141+ * system-wide default {@link java.nio.channels.spi.SelectorProvider}
142+ * object. </p>
143+ *
144+ * @return A new pipe
145+ *
146+ * @throws IOException
147+ * If an I/O error occurs
148+ */
149+ public static Pipe open() throws IOException {
150+ return SelectorProvider.provider().openPipe();
151+ }
152+
153+}
java/pkg/java/nio/channels/ReadableByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/ReadableByteChannel.java+108−0
@@ -0,0 +1,108 @@
1+/*
2+ * Copyright (c) 2000, 2001, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.ByteBuffer;
30+
31+
32+/**
33+ * A channel that can read bytes.
34+ *
35+ * <p> Only one read operation upon a readable channel may be in progress at
36+ * any given time. If one thread initiates a read operation upon a channel
37+ * then any other thread that attempts to initiate another read operation will
38+ * block until the first operation is complete. Whether or not other kinds of
39+ * I/O operations may proceed concurrently with a read operation depends upon
40+ * the type of the channel. </p>
41+ *
42+ *
43+ * @author Mark Reinhold
44+ * @author JSR-51 Expert Group
45+ * @since 1.4
46+ */
47+
48+public interface ReadableByteChannel extends Channel {
49+
50+ /**
51+ * Reads a sequence of bytes from this channel into the given buffer.
52+ *
53+ * <p> An attempt is made to read up to <i>r</i> bytes from the channel,
54+ * where <i>r</i> is the number of bytes remaining in the buffer, that is,
55+ * <tt>dst.remaining()</tt>, at the moment this method is invoked.
56+ *
57+ * <p> Suppose that a byte sequence of length <i>n</i> is read, where
58+ * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
59+ * This byte sequence will be transferred into the buffer so that the first
60+ * byte in the sequence is at index <i>p</i> and the last byte is at index
61+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>,
62+ * where <i>p</i> is the buffer's position at the moment this method is
63+ * invoked. Upon return the buffer's position will be equal to
64+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
65+ *
66+ * <p> A read operation might not fill the buffer, and in fact it might not
67+ * read any bytes at all. Whether or not it does so depends upon the
68+ * nature and state of the channel. A socket channel in non-blocking mode,
69+ * for example, cannot read any more bytes than are immediately available
70+ * from the socket's input buffer; similarly, a file channel cannot read
71+ * any more bytes than remain in the file. It is guaranteed, however, that
72+ * if a channel is in blocking mode and there is at least one byte
73+ * remaining in the buffer then this method will block until at least one
74+ * byte is read.
75+ *
76+ * <p> This method may be invoked at any time. If another thread has
77+ * already initiated a read operation upon this channel, however, then an
78+ * invocation of this method will block until the first operation is
79+ * complete. </p>
80+ *
81+ * @param dst
82+ * The buffer into which bytes are to be transferred
83+ *
84+ * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the
85+ * channel has reached end-of-stream
86+ *
87+ * @throws NonReadableChannelException
88+ * If this channel was not opened for reading
89+ *
90+ * @throws ClosedChannelException
91+ * If this channel is closed
92+ *
93+ * @throws AsynchronousCloseException
94+ * If another thread closes this channel
95+ * while the read operation is in progress
96+ *
97+ * @throws ClosedByInterruptException
98+ * If another thread interrupts the current thread
99+ * while the read operation is in progress, thereby
100+ * closing the channel and setting the current thread's
101+ * interrupt status
102+ *
103+ * @throws IOException
104+ * If some other I/O error occurs
105+ */
106+ public int read(ByteBuffer dst) throws IOException;
107+
108+}
java/pkg/java/nio/channels/ScatteringByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/ScatteringByteChannel.java+162−0
@@ -0,0 +1,162 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.ByteBuffer;
30+
31+
32+/**
33+ * A channel that can read bytes into a sequence of buffers.
34+ *
35+ * <p> A <i>scattering</i> read operation reads, in a single invocation, a
36+ * sequence of bytes into one or more of a given sequence of buffers.
37+ * Scattering reads are often useful when implementing network protocols or
38+ * file formats that, for example, group data into segments consisting of one
39+ * or more fixed-length headers followed by a variable-length body. Similar
40+ * <i>gathering</i> write operations are defined in the {@link
41+ * GatheringByteChannel} interface. </p>
42+ *
43+ *
44+ * @author Mark Reinhold
45+ * @author JSR-51 Expert Group
46+ * @since 1.4
47+ */
48+
49+public interface ScatteringByteChannel
50+ extends ReadableByteChannel
51+{
52+
53+ /**
54+ * Reads a sequence of bytes from this channel into a subsequence of the
55+ * given buffers.
56+ *
57+ * <p> An invocation of this method attempts to read up to <i>r</i> bytes
58+ * from this channel, where <i>r</i> is the total number of bytes remaining
59+ * the specified subsequence of the given buffer array, that is,
60+ *
61+ * <blockquote><pre>
62+ * dsts[offset].remaining()
63+ * + dsts[offset+1].remaining()
64+ * + ... + dsts[offset+length-1].remaining()</pre></blockquote>
65+ *
66+ * at the moment that this method is invoked.
67+ *
68+ * <p> Suppose that a byte sequence of length <i>n</i> is read, where
69+ * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
70+ * Up to the first <tt>dsts[offset].remaining()</tt> bytes of this sequence
71+ * are transferred into buffer <tt>dsts[offset]</tt>, up to the next
72+ * <tt>dsts[offset+1].remaining()</tt> bytes are transferred into buffer
73+ * <tt>dsts[offset+1]</tt>, and so forth, until the entire byte sequence
74+ * is transferred into the given buffers. As many bytes as possible are
75+ * transferred into each buffer, hence the final position of each updated
76+ * buffer, except the last updated buffer, is guaranteed to be equal to
77+ * that buffer's limit.
78+ *
79+ * <p> This method may be invoked at any time. If another thread has
80+ * already initiated a read operation upon this channel, however, then an
81+ * invocation of this method will block until the first operation is
82+ * complete. </p>
83+ *
84+ * @param dsts
85+ * The buffers into which bytes are to be transferred
86+ *
87+ * @param offset
88+ * The offset within the buffer array of the first buffer into
89+ * which bytes are to be transferred; must be non-negative and no
90+ * larger than <tt>dsts.length</tt>
91+ *
92+ * @param length
93+ * The maximum number of buffers to be accessed; must be
94+ * non-negative and no larger than
95+ * <tt>dsts.length</tt>&nbsp;-&nbsp;<tt>offset</tt>
96+ *
97+ * @return The number of bytes read, possibly zero,
98+ * or <tt>-1</tt> if the channel has reached end-of-stream
99+ *
100+ * @throws IndexOutOfBoundsException
101+ * If the preconditions on the <tt>offset</tt> and <tt>length</tt>
102+ * parameters do not hold
103+ *
104+ * @throws NonReadableChannelException
105+ * If this channel was not opened for reading
106+ *
107+ * @throws ClosedChannelException
108+ * If this channel is closed
109+ *
110+ * @throws AsynchronousCloseException
111+ * If another thread closes this channel
112+ * while the read operation is in progress
113+ *
114+ * @throws ClosedByInterruptException
115+ * If another thread interrupts the current thread
116+ * while the read operation is in progress, thereby
117+ * closing the channel and setting the current thread's
118+ * interrupt status
119+ *
120+ * @throws IOException
121+ * If some other I/O error occurs
122+ */
123+ public long read(ByteBuffer[] dsts, int offset, int length)
124+ throws IOException;
125+
126+ /**
127+ * Reads a sequence of bytes from this channel into the given buffers.
128+ *
129+ * <p> An invocation of this method of the form <tt>c.read(dsts)</tt>
130+ * behaves in exactly the same manner as the invocation
131+ *
132+ * <blockquote><pre>
133+ * c.read(dsts, 0, dsts.length);</pre></blockquote>
134+ *
135+ * @param dsts
136+ * The buffers into which bytes are to be transferred
137+ *
138+ * @return The number of bytes read, possibly zero,
139+ * or <tt>-1</tt> if the channel has reached end-of-stream
140+ *
141+ * @throws NonReadableChannelException
142+ * If this channel was not opened for reading
143+ *
144+ * @throws ClosedChannelException
145+ * If this channel is closed
146+ *
147+ * @throws AsynchronousCloseException
148+ * If another thread closes this channel
149+ * while the read operation is in progress
150+ *
151+ * @throws ClosedByInterruptException
152+ * If another thread interrupts the current thread
153+ * while the read operation is in progress, thereby
154+ * closing the channel and setting the current thread's
155+ * interrupt status
156+ *
157+ * @throws IOException
158+ * If some other I/O error occurs
159+ */
160+ public long read(ByteBuffer[] dsts) throws IOException;
161+
162+}
java/pkg/java/nio/channels/SeekableByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/SeekableByteChannel.java+168−0
@@ -0,0 +1,168 @@
1+/*
2+ * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.nio.ByteBuffer;
29+import java.io.IOException;
30+
31+/**
32+ * A byte channel that maintains a current <i>position</i> and allows the
33+ * position to be changed.
34+ *
35+ * <p> A seekable byte channel is connected to an entity, typically a file,
36+ * that contains a variable-length sequence of bytes that can be read and
37+ * written. The current position can be {@link #position() <i>queried</i>} and
38+ * {@link #position(long) <i>modified</i>}. The channel also provides access to
39+ * the current <i>size</i> of the entity to which the channel is connected. The
40+ * size increases when bytes are written beyond its current size; the size
41+ * decreases when it is {@link #truncate <i>truncated</i>}.
42+ *
43+ * <p> The {@link #position(long) position} and {@link #truncate truncate} methods
44+ * which do not otherwise have a value to return are specified to return the
45+ * channel upon which they are invoked. This allows method invocations to be
46+ * chained. Implementations of this interface should specialize the return type
47+ * so that method invocations on the implementation class can be chained.
48+ *
49+ * @since 1.7
50+ * @see java.nio.file.Files#newByteChannel
51+ */
52+
53+public interface SeekableByteChannel
54+ extends ByteChannel
55+{
56+ /**
57+ * Reads a sequence of bytes from this channel into the given buffer.
58+ *
59+ * <p> Bytes are read starting at this channel's current position, and
60+ * then the position is updated with the number of bytes actually read.
61+ * Otherwise this method behaves exactly as specified in the {@link
62+ * ReadableByteChannel} interface.
63+ */
64+ @Override
65+ int read(ByteBuffer dst) throws IOException;
66+
67+ /**
68+ * Writes a sequence of bytes to this channel from the given buffer.
69+ *
70+ * <p> Bytes are written starting at this channel's current position, unless
71+ * the channel is connected to an entity such as a file that is opened with
72+ * the {@link java.nio.file.StandardOpenOption#APPEND APPEND} option, in
73+ * which case the position is first advanced to the end. The entity to which
74+ * the channel is connected is grown, if necessary, to accommodate the
75+ * written bytes, and then the position is updated with the number of bytes
76+ * actually written. Otherwise this method behaves exactly as specified by
77+ * the {@link WritableByteChannel} interface.
78+ */
79+ @Override
80+ int write(ByteBuffer src) throws IOException;
81+
82+ /**
83+ * Returns this channel's position.
84+ *
85+ * @return This channel's position,
86+ * a non-negative integer counting the number of bytes
87+ * from the beginning of the entity to the current position
88+ *
89+ * @throws ClosedChannelException
90+ * If this channel is closed
91+ * @throws IOException
92+ * If some other I/O error occurs
93+ */
94+ long position() throws IOException;
95+
96+ /**
97+ * Sets this channel's position.
98+ *
99+ * <p> Setting the position to a value that is greater than the current size
100+ * is legal but does not change the size of the entity. A later attempt to
101+ * read bytes at such a position will immediately return an end-of-file
102+ * indication. A later attempt to write bytes at such a position will cause
103+ * the entity to grow to accommodate the new bytes; the values of any bytes
104+ * between the previous end-of-file and the newly-written bytes are
105+ * unspecified.
106+ *
107+ * <p> Setting the channel's position is not recommended when connected to
108+ * an entity, typically a file, that is opened with the {@link
109+ * java.nio.file.StandardOpenOption#APPEND APPEND} option. When opened for
110+ * append, the position is first advanced to the end before writing.
111+ *
112+ * @param newPosition
113+ * The new position, a non-negative integer counting
114+ * the number of bytes from the beginning of the entity
115+ *
116+ * @return This channel
117+ *
118+ * @throws ClosedChannelException
119+ * If this channel is closed
120+ * @throws IllegalArgumentException
121+ * If the new position is negative
122+ * @throws IOException
123+ * If some other I/O error occurs
124+ */
125+ SeekableByteChannel position(long newPosition) throws IOException;
126+
127+ /**
128+ * Returns the current size of entity to which this channel is connected.
129+ *
130+ * @return The current size, measured in bytes
131+ *
132+ * @throws ClosedChannelException
133+ * If this channel is closed
134+ * @throws IOException
135+ * If some other I/O error occurs
136+ */
137+ long size() throws IOException;
138+
139+ /**
140+ * Truncates the entity, to which this channel is connected, to the given
141+ * size.
142+ *
143+ * <p> If the given size is less than the current size then the entity is
144+ * truncated, discarding any bytes beyond the new end. If the given size is
145+ * greater than or equal to the current size then the entity is not modified.
146+ * In either case, if the current position is greater than the given size
147+ * then it is set to that size.
148+ *
149+ * <p> An implementation of this interface may prohibit truncation when
150+ * connected to an entity, typically a file, opened with the {@link
151+ * java.nio.file.StandardOpenOption#APPEND APPEND} option.
152+ *
153+ * @param size
154+ * The new size, a non-negative byte count
155+ *
156+ * @return This channel
157+ *
158+ * @throws NonWritableChannelException
159+ * If this channel was not opened for writing
160+ * @throws ClosedChannelException
161+ * If this channel is closed
162+ * @throws IllegalArgumentException
163+ * If the new size is negative
164+ * @throws IOException
165+ * If some other I/O error occurs
166+ */
167+ SeekableByteChannel truncate(long size) throws IOException;
168+}
java/pkg/java/nio/channels/SelectableChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/SelectableChannel.java+342−0
@@ -0,0 +1,342 @@
1+/*
2+ * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.channels.spi.AbstractInterruptibleChannel;
30+import java.nio.channels.spi.SelectorProvider;
31+
32+
33+/**
34+ * A channel that can be multiplexed via a {@link Selector}.
35+ *
36+ * <p> In order to be used with a selector, an instance of this class must
37+ * first be <i>registered</i> via the {@link #register(Selector,int,Object)
38+ * register} method. This method returns a new {@link SelectionKey} object
39+ * that represents the channel's registration with the selector.
40+ *
41+ * <p> Once registered with a selector, a channel remains registered until it
42+ * is <i>deregistered</i>. This involves deallocating whatever resources were
43+ * allocated to the channel by the selector.
44+ *
45+ * <p> A channel cannot be deregistered directly; instead, the key representing
46+ * its registration must be <i>cancelled</i>. Cancelling a key requests that
47+ * the channel be deregistered during the selector's next selection operation.
48+ * A key may be cancelled explicitly by invoking its {@link
49+ * SelectionKey#cancel() cancel} method. All of a channel's keys are cancelled
50+ * implicitly when the channel is closed, whether by invoking its {@link
51+ * Channel#close close} method or by interrupting a thread blocked in an I/O
52+ * operation upon the channel.
53+ *
54+ * <p> If the selector itself is closed then the channel will be deregistered,
55+ * and the key representing its registration will be invalidated, without
56+ * further delay.
57+ *
58+ * <p> A channel may be registered at most once with any particular selector.
59+ *
60+ * <p> Whether or not a channel is registered with one or more selectors may be
61+ * determined by invoking the {@link #isRegistered isRegistered} method.
62+ *
63+ * <p> Selectable channels are safe for use by multiple concurrent
64+ * threads. </p>
65+ *
66+ *
67+ * <a name="bm">
68+ * <h4>Blocking mode</h4>
69+ *
70+ * A selectable channel is either in <i>blocking</i> mode or in
71+ * <i>non-blocking</i> mode. In blocking mode, every I/O operation invoked
72+ * upon the channel will block until it completes. In non-blocking mode an I/O
73+ * operation will never block and may transfer fewer bytes than were requested
74+ * or possibly no bytes at all. The blocking mode of a selectable channel may
75+ * be determined by invoking its {@link #isBlocking isBlocking} method.
76+ *
77+ * <p> Newly-created selectable channels are always in blocking mode.
78+ * Non-blocking mode is most useful in conjunction with selector-based
79+ * multiplexing. A channel must be placed into non-blocking mode before being
80+ * registered with a selector, and may not be returned to blocking mode until
81+ * it has been deregistered.
82+ *
83+ *
84+ * @author Mark Reinhold
85+ * @author JSR-51 Expert Group
86+ * @since 1.4
87+ *
88+ * @see SelectionKey
89+ * @see Selector
90+ */
91+
92+public abstract class SelectableChannel
93+ extends AbstractInterruptibleChannel
94+ implements Channel
95+{
96+
97+ /**
98+ * Initializes a new instance of this class.
99+ */
100+ protected SelectableChannel() { }
101+
102+ /**
103+ * Returns the provider that created this channel.
104+ *
105+ * @return The provider that created this channel
106+ */
107+ public abstract SelectorProvider provider();
108+
109+ /**
110+ * Returns an <a href="SelectionKey.html#opsets">operation set</a>
111+ * identifying this channel's supported operations. The bits that are set
112+ * in this integer value denote exactly the operations that are valid for
113+ * this channel. This method always returns the same value for a given
114+ * concrete channel class. </p>
115+ *
116+ * @return The valid-operation set
117+ */
118+ public abstract int validOps();
119+
120+ // Internal state:
121+ // keySet, may be empty but is never null, typ. a tiny array
122+ // boolean isRegistered, protected by key set
123+ // regLock, lock object to prevent duplicate registrations
124+ // boolean isBlocking, protected by regLock
125+
126+ /**
127+ * Tells whether or not this channel is currently registered with any
128+ * selectors. A newly-created channel is not registered.
129+ *
130+ * <p> Due to the inherent delay between key cancellation and channel
131+ * deregistration, a channel may remain registered for some time after all
132+ * of its keys have been cancelled. A channel may also remain registered
133+ * for some time after it is closed. </p>
134+ *
135+ * @return <tt>true</tt> if, and only if, this channel is registered
136+ */
137+ public abstract boolean isRegistered();
138+ //
139+ // sync(keySet) { return isRegistered; }
140+
141+ /**
142+ * Retrieves the key representing the channel's registration with the given
143+ * selector. </p>
144+ *
145+ * @return The key returned when this channel was last registered with the
146+ * given selector, or <tt>null</tt> if this channel is not
147+ * currently registered with that selector
148+ */
149+ public abstract SelectionKey keyFor(Selector sel);
150+ //
151+ // sync(keySet) { return findKey(sel); }
152+
153+ /**
154+ * Registers this channel with the given selector, returning a selection
155+ * key.
156+ *
157+ * <p> If this channel is currently registered with the given selector then
158+ * the selection key representing that registration is returned. The key's
159+ * interest set will have been changed to <tt>ops</tt>, as if by invoking
160+ * the {@link SelectionKey#interestOps(int) interestOps(int)} method. If
161+ * the <tt>att</tt> argument is not <tt>null</tt> then the key's attachment
162+ * will have been set to that value. A {@link CancelledKeyException} will
163+ * be thrown if the key has already been cancelled.
164+ *
165+ * <p> Otherwise this channel has not yet been registered with the given
166+ * selector, so it is registered and the resulting new key is returned.
167+ * The key's initial interest set will be <tt>ops</tt> and its attachment
168+ * will be <tt>att</tt>.
169+ *
170+ * <p> This method may be invoked at any time. If this method is invoked
171+ * while another invocation of this method or of the {@link
172+ * #configureBlocking(boolean) configureBlocking} method is in progress
173+ * then it will first block until the other operation is complete. This
174+ * method will then synchronize on the selector's key set and therefore may
175+ * block if invoked concurrently with another registration or selection
176+ * operation involving the same selector. </p>
177+ *
178+ * <p> If this channel is closed while this operation is in progress then
179+ * the key returned by this method will have been cancelled and will
180+ * therefore be invalid. </p>
181+ *
182+ * @param sel
183+ * The selector with which this channel is to be registered
184+ *
185+ * @param ops
186+ * The interest set for the resulting key
187+ *
188+ * @param att
189+ * The attachment for the resulting key; may be <tt>null</tt>
190+ *
191+ * @throws ClosedChannelException
192+ * If this channel is closed
193+ *
194+ * @throws ClosedSelectorException
195+ * If the selector is closed
196+ *
197+ * @throws IllegalBlockingModeException
198+ * If this channel is in blocking mode
199+ *
200+ * @throws IllegalSelectorException
201+ * If this channel was not created by the same provider
202+ * as the given selector
203+ *
204+ * @throws CancelledKeyException
205+ * If this channel is currently registered with the given selector
206+ * but the corresponding key has already been cancelled
207+ *
208+ * @throws IllegalArgumentException
209+ * If a bit in the <tt>ops</tt> set does not correspond to an
210+ * operation that is supported by this channel, that is, if
211+ * <tt>set & ~validOps() != 0</tt>
212+ *
213+ * @return A key representing the registration of this channel with
214+ * the given selector
215+ */
216+ public abstract SelectionKey register(Selector sel, int ops, Object att)
217+ throws ClosedChannelException;
218+ //
219+ // sync(regLock) {
220+ // sync(keySet) { look for selector }
221+ // if (channel found) { set interest ops -- may block in selector;
222+ // return key; }
223+ // create new key -- may block somewhere in selector;
224+ // sync(keySet) { add key; }
225+ // attach(attachment);
226+ // return key;
227+ // }
228+
229+ /**
230+ * Registers this channel with the given selector, returning a selection
231+ * key.
232+ *
233+ * <p> An invocation of this convenience method of the form
234+ *
235+ * <blockquote><tt>sc.register(sel, ops)</tt></blockquote>
236+ *
237+ * behaves in exactly the same way as the invocation
238+ *
239+ * <blockquote><tt>sc.{@link
240+ * #register(java.nio.channels.Selector,int,java.lang.Object)
241+ * register}(sel, ops, null)</tt></blockquote>
242+ *
243+ * @param sel
244+ * The selector with which this channel is to be registered
245+ *
246+ * @param ops
247+ * The interest set for the resulting key
248+ *
249+ * @throws ClosedChannelException
250+ * If this channel is closed
251+ *
252+ * @throws ClosedSelectorException
253+ * If the selector is closed
254+ *
255+ * @throws IllegalBlockingModeException
256+ * If this channel is in blocking mode
257+ *
258+ * @throws IllegalSelectorException
259+ * If this channel was not created by the same provider
260+ * as the given selector
261+ *
262+ * @throws CancelledKeyException
263+ * If this channel is currently registered with the given selector
264+ * but the corresponding key has already been cancelled
265+ *
266+ * @throws IllegalArgumentException
267+ * If a bit in <tt>ops</tt> does not correspond to an operation
268+ * that is supported by this channel, that is, if <tt>set &
269+ * ~validOps() != 0</tt>
270+ *
271+ * @return A key representing the registration of this channel with
272+ * the given selector
273+ */
274+ public final SelectionKey register(Selector sel, int ops)
275+ throws ClosedChannelException
276+ {
277+ return register(sel, ops, null);
278+ }
279+
280+ /**
281+ * Adjusts this channel's blocking mode.
282+ *
283+ * <p> If this channel is registered with one or more selectors then an
284+ * attempt to place it into blocking mode will cause an {@link
285+ * IllegalBlockingModeException} to be thrown.
286+ *
287+ * <p> This method may be invoked at any time. The new blocking mode will
288+ * only affect I/O operations that are initiated after this method returns.
289+ * For some implementations this may require blocking until all pending I/O
290+ * operations are complete.
291+ *
292+ * <p> If this method is invoked while another invocation of this method or
293+ * of the {@link #register(Selector, int) register} method is in progress
294+ * then it will first block until the other operation is complete. </p>
295+ *
296+ * @param block If <tt>true</tt> then this channel will be placed in
297+ * blocking mode; if <tt>false</tt> then it will be placed
298+ * non-blocking mode
299+ *
300+ * @return This selectable channel
301+ *
302+ * @throws ClosedChannelException
303+ * If this channel is closed
304+ *
305+ * @throws IllegalBlockingModeException
306+ * If <tt>block</tt> is <tt>true</tt> and this channel is
307+ * registered with one or more selectors
308+ *
309+ * @throws IOException
310+ * If an I/O error occurs
311+ */
312+ public abstract SelectableChannel configureBlocking(boolean block)
313+ throws IOException;
314+ //
315+ // sync(regLock) {
316+ // sync(keySet) { throw IBME if block && isRegistered; }
317+ // change mode;
318+ // }
319+
320+ /**
321+ * Tells whether or not every I/O operation on this channel will block
322+ * until it completes. A newly-created channel is always in blocking mode.
323+ *
324+ * <p> If this channel is closed then the value returned by this method is
325+ * not specified. </p>
326+ *
327+ * @return <tt>true</tt> if, and only if, this channel is in blocking mode
328+ */
329+ public abstract boolean isBlocking();
330+
331+ /**
332+ * Retrieves the object upon which the {@link #configureBlocking
333+ * configureBlocking} and {@link #register register} methods synchronize.
334+ * This is often useful in the implementation of adaptors that require a
335+ * specific blocking mode to be maintained for a short period of time.
336+ * </p>
337+ *
338+ * @return The blocking-mode lock object
339+ */
340+ public abstract Object blockingLock();
341+
342+}
java/pkg/java/nio/channels/SelectionKey.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/SelectionKey.java+401−0
@@ -0,0 +1,401 @@
1+/*
2+ * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
29+import java.io.IOException;
30+
31+
32+/**
33+ * A token representing the registration of a {@link SelectableChannel} with a
34+ * {@link Selector}.
35+ *
36+ * <p> A selection key is created each time a channel is registered with a
37+ * selector. A key remains valid until it is <i>cancelled</i> by invoking its
38+ * {@link #cancel cancel} method, by closing its channel, or by closing its
39+ * selector. Cancelling a key does not immediately remove it from its
40+ * selector; it is instead added to the selector's <a
41+ * href="Selector.html#ks"><i>cancelled-key set</i></a> for removal during the
42+ * next selection operation. The validity of a key may be tested by invoking
43+ * its {@link #isValid isValid} method.
44+ *
45+ * <a name="opsets">
46+ *
47+ * <p> A selection key contains two <i>operation sets</i> represented as
48+ * integer values. Each bit of an operation set denotes a category of
49+ * selectable operations that are supported by the key's channel.
50+ *
51+ * <ul>
52+ *
53+ * <li><p> The <i>interest set</i> determines which operation categories will
54+ * be tested for readiness the next time one of the selector's selection
55+ * methods is invoked. The interest set is initialized with the value given
56+ * when the key is created; it may later be changed via the {@link
57+ * #interestOps(int)} method. </p></li>
58+ *
59+ * <li><p> The <i>ready set</i> identifies the operation categories for which
60+ * the key's channel has been detected to be ready by the key's selector.
61+ * The ready set is initialized to zero when the key is created; it may later
62+ * be updated by the selector during a selection operation, but it cannot be
63+ * updated directly. </p></li>
64+ *
65+ * </ul>
66+ *
67+ * <p> That a selection key's ready set indicates that its channel is ready for
68+ * some operation category is a hint, but not a guarantee, that an operation in
69+ * such a category may be performed by a thread without causing the thread to
70+ * block. A ready set is most likely to be accurate immediately after the
71+ * completion of a selection operation. It is likely to be made inaccurate by
72+ * external events and by I/O operations that are invoked upon the
73+ * corresponding channel.
74+ *
75+ * <p> This class defines all known operation-set bits, but precisely which
76+ * bits are supported by a given channel depends upon the type of the channel.
77+ * Each subclass of {@link SelectableChannel} defines an {@link
78+ * SelectableChannel#validOps() validOps()} method which returns a set
79+ * identifying just those operations that are supported by the channel. An
80+ * attempt to set or test an operation-set bit that is not supported by a key's
81+ * channel will result in an appropriate run-time exception.
82+ *
83+ * <p> It is often necessary to associate some application-specific data with a
84+ * selection key, for example an object that represents the state of a
85+ * higher-level protocol and handles readiness notifications in order to
86+ * implement that protocol. Selection keys therefore support the
87+ * <i>attachment</i> of a single arbitrary object to a key. An object can be
88+ * attached via the {@link #attach attach} method and then later retrieved via
89+ * the {@link #attachment() attachment} method.
90+ *
91+ * <p> Selection keys are safe for use by multiple concurrent threads. The
92+ * operations of reading and writing the interest set will, in general, be
93+ * synchronized with certain operations of the selector. Exactly how this
94+ * synchronization is performed is implementation-dependent: In a naive
95+ * implementation, reading or writing the interest set may block indefinitely
96+ * if a selection operation is already in progress; in a high-performance
97+ * implementation, reading or writing the interest set may block briefly, if at
98+ * all. In any case, a selection operation will always use the interest-set
99+ * value that was current at the moment that the operation began. </p>
100+ *
101+ *
102+ * @author Mark Reinhold
103+ * @author JSR-51 Expert Group
104+ * @since 1.4
105+ *
106+ * @see SelectableChannel
107+ * @see Selector
108+ */
109+
110+public abstract class SelectionKey {
111+
112+ /**
113+ * Constructs an instance of this class.
114+ */
115+ protected SelectionKey() { }
116+
117+
118+ // -- Channel and selector operations --
119+
120+ /**
121+ * Returns the channel for which this key was created. This method will
122+ * continue to return the channel even after the key is cancelled. </p>
123+ *
124+ * @return This key's channel
125+ */
126+ public abstract SelectableChannel channel();
127+
128+ /**
129+ * Returns the selector for which this key was created. This method will
130+ * continue to return the selector even after the key is cancelled. </p>
131+ *
132+ * @return This key's selector
133+ */
134+ public abstract Selector selector();
135+
136+ /**
137+ * Tells whether or not this key is valid.
138+ *
139+ * <p> A key is valid upon creation and remains so until it is cancelled,
140+ * its channel is closed, or its selector is closed. </p>
141+ *
142+ * @return <tt>true</tt> if, and only if, this key is valid
143+ */
144+ public abstract boolean isValid();
145+
146+ /**
147+ * Requests that the registration of this key's channel with its selector
148+ * be cancelled. Upon return the key will be invalid and will have been
149+ * added to its selector's cancelled-key set. The key will be removed from
150+ * all of the selector's key sets during the next selection operation.
151+ *
152+ * <p> If this key has already been cancelled then invoking this method has
153+ * no effect. Once cancelled, a key remains forever invalid. </p>
154+ *
155+ * <p> This method may be invoked at any time. It synchronizes on the
156+ * selector's cancelled-key set, and therefore may block briefly if invoked
157+ * concurrently with a cancellation or selection operation involving the
158+ * same selector. </p>
159+ */
160+ public abstract void cancel();
161+
162+
163+ // -- Operation-set accessors --
164+
165+ /**
166+ * Retrieves this key's interest set.
167+ *
168+ * <p> It is guaranteed that the returned set will only contain operation
169+ * bits that are valid for this key's channel.
170+ *
171+ * <p> This method may be invoked at any time. Whether or not it blocks,
172+ * and for how long, is implementation-dependent. </p>
173+ *
174+ * @return This key's interest set
175+ *
176+ * @throws CancelledKeyException
177+ * If this key has been cancelled
178+ */
179+ public abstract int interestOps();
180+
181+ /**
182+ * Sets this key's interest set to the given value.
183+ *
184+ * <p> This method may be invoked at any time. Whether or not it blocks,
185+ * and for how long, is implementation-dependent. </p>
186+ *
187+ * @param ops The new interest set
188+ *
189+ * @return This selection key
190+ *
191+ * @throws IllegalArgumentException
192+ * If a bit in the set does not correspond to an operation that
193+ * is supported by this key's channel, that is, if
194+ * <tt>(ops & ~channel().validOps()) != 0</tt>
195+ *
196+ * @throws CancelledKeyException
197+ * If this key has been cancelled
198+ */
199+ public abstract SelectionKey interestOps(int ops);
200+
201+ /**
202+ * Retrieves this key's ready-operation set.
203+ *
204+ * <p> It is guaranteed that the returned set will only contain operation
205+ * bits that are valid for this key's channel. </p>
206+ *
207+ * @return This key's ready-operation set
208+ *
209+ * @throws CancelledKeyException
210+ * If this key has been cancelled
211+ */
212+ public abstract int readyOps();
213+
214+
215+ // -- Operation bits and bit-testing convenience methods --
216+
217+ /**
218+ * Operation-set bit for read operations.
219+ *
220+ * <p> Suppose that a selection key's interest set contains
221+ * <tt>OP_READ</tt> at the start of a <a
222+ * href="Selector.html#selop">selection operation</a>. If the selector
223+ * detects that the corresponding channel is ready for reading, has reached
224+ * end-of-stream, has been remotely shut down for further reading, or has
225+ * an error pending, then it will add <tt>OP_READ</tt> to the key's
226+ * ready-operation set and add the key to its selected-key&nbsp;set. </p>
227+ */
228+ public static final int OP_READ = 1 << 0;
229+
230+ /**
231+ * Operation-set bit for write operations. </p>
232+ *
233+ * <p> Suppose that a selection key's interest set contains
234+ * <tt>OP_WRITE</tt> at the start of a <a
235+ * href="Selector.html#selop">selection operation</a>. If the selector
236+ * detects that the corresponding channel is ready for writing, has been
237+ * remotely shut down for further writing, or has an error pending, then it
238+ * will add <tt>OP_WRITE</tt> to the key's ready set and add the key to its
239+ * selected-key&nbsp;set. </p>
240+ */
241+ public static final int OP_WRITE = 1 << 2;
242+
243+ /**
244+ * Operation-set bit for socket-connect operations. </p>
245+ *
246+ * <p> Suppose that a selection key's interest set contains
247+ * <tt>OP_CONNECT</tt> at the start of a <a
248+ * href="Selector.html#selop">selection operation</a>. If the selector
249+ * detects that the corresponding socket channel is ready to complete its
250+ * connection sequence, or has an error pending, then it will add
251+ * <tt>OP_CONNECT</tt> to the key's ready set and add the key to its
252+ * selected-key&nbsp;set. </p>
253+ */
254+ public static final int OP_CONNECT = 1 << 3;
255+
256+ /**
257+ * Operation-set bit for socket-accept operations. </p>
258+ *
259+ * <p> Suppose that a selection key's interest set contains
260+ * <tt>OP_ACCEPT</tt> at the start of a <a
261+ * href="Selector.html#selop">selection operation</a>. If the selector
262+ * detects that the corresponding server-socket channel is ready to accept
263+ * another connection, or has an error pending, then it will add
264+ * <tt>OP_ACCEPT</tt> to the key's ready set and add the key to its
265+ * selected-key&nbsp;set. </p>
266+ */
267+ public static final int OP_ACCEPT = 1 << 4;
268+
269+ /**
270+ * Tests whether this key's channel is ready for reading.
271+ *
272+ * <p> An invocation of this method of the form <tt>k.isReadable()</tt>
273+ * behaves in exactly the same way as the expression
274+ *
275+ * <blockquote><pre>
276+ * k.readyOps()&nbsp;&amp;&nbsp;OP_READ&nbsp;!=&nbsp;0</pre></blockquote>
277+ *
278+ * <p> If this key's channel does not support read operations then this
279+ * method always returns <tt>false</tt>. </p>
280+ *
281+ * @return <tt>true</tt> if, and only if,
282+ * <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_READ</tt> is
283+ * nonzero
284+ *
285+ * @throws CancelledKeyException
286+ * If this key has been cancelled
287+ */
288+ public final boolean isReadable() {
289+ return (readyOps() & OP_READ) != 0;
290+ }
291+
292+ /**
293+ * Tests whether this key's channel is ready for writing.
294+ *
295+ * <p> An invocation of this method of the form <tt>k.isWritable()</tt>
296+ * behaves in exactly the same way as the expression
297+ *
298+ * <blockquote><pre>
299+ * k.readyOps()&nbsp;&amp;&nbsp;OP_WRITE&nbsp;!=&nbsp;0</pre></blockquote>
300+ *
301+ * <p> If this key's channel does not support write operations then this
302+ * method always returns <tt>false</tt>. </p>
303+ *
304+ * @return <tt>true</tt> if, and only if,
305+ * <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_WRITE</tt>
306+ * is nonzero
307+ *
308+ * @throws CancelledKeyException
309+ * If this key has been cancelled
310+ */
311+ public final boolean isWritable() {
312+ return (readyOps() & OP_WRITE) != 0;
313+ }
314+
315+ /**
316+ * Tests whether this key's channel has either finished, or failed to
317+ * finish, its socket-connection operation.
318+ *
319+ * <p> An invocation of this method of the form <tt>k.isConnectable()</tt>
320+ * behaves in exactly the same way as the expression
321+ *
322+ * <blockquote><pre>
323+ * k.readyOps()&nbsp;&amp;&nbsp;OP_CONNECT&nbsp;!=&nbsp;0</pre></blockquote>
324+ *
325+ * <p> If this key's channel does not support socket-connect operations
326+ * then this method always returns <tt>false</tt>. </p>
327+ *
328+ * @return <tt>true</tt> if, and only if,
329+ * <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_CONNECT</tt>
330+ * is nonzero
331+ *
332+ * @throws CancelledKeyException
333+ * If this key has been cancelled
334+ */
335+ public final boolean isConnectable() {
336+ return (readyOps() & OP_CONNECT) != 0;
337+ }
338+
339+ /**
340+ * Tests whether this key's channel is ready to accept a new socket
341+ * connection.
342+ *
343+ * <p> An invocation of this method of the form <tt>k.isAcceptable()</tt>
344+ * behaves in exactly the same way as the expression
345+ *
346+ * <blockquote><pre>
347+ * k.readyOps()&nbsp;&amp;&nbsp;OP_ACCEPT&nbsp;!=&nbsp;0</pre></blockquote>
348+ *
349+ * <p> If this key's channel does not support socket-accept operations then
350+ * this method always returns <tt>false</tt>. </p>
351+ *
352+ * @return <tt>true</tt> if, and only if,
353+ * <tt>readyOps()</tt>&nbsp;<tt>&</tt>&nbsp;<tt>OP_ACCEPT</tt>
354+ * is nonzero
355+ *
356+ * @throws CancelledKeyException
357+ * If this key has been cancelled
358+ */
359+ public final boolean isAcceptable() {
360+ return (readyOps() & OP_ACCEPT) != 0;
361+ }
362+
363+
364+ // -- Attachments --
365+
366+ private volatile Object attachment = null;
367+
368+ private static final AtomicReferenceFieldUpdater<SelectionKey,Object>
369+ attachmentUpdater = AtomicReferenceFieldUpdater.newUpdater(
370+ SelectionKey.class, Object.class, "attachment"
371+ );
372+
373+ /**
374+ * Attaches the given object to this key.
375+ *
376+ * <p> An attached object may later be retrieved via the {@link #attachment()
377+ * attachment} method. Only one object may be attached at a time; invoking
378+ * this method causes any previous attachment to be discarded. The current
379+ * attachment may be discarded by attaching <tt>null</tt>. </p>
380+ *
381+ * @param ob
382+ * The object to be attached; may be <tt>null</tt>
383+ *
384+ * @return The previously-attached object, if any,
385+ * otherwise <tt>null</tt>
386+ */
387+ public final Object attach(Object ob) {
388+ return attachmentUpdater.getAndSet(this, ob);
389+ }
390+
391+ /**
392+ * Retrieves the current attachment. </p>
393+ *
394+ * @return The object currently attached to this key,
395+ * or <tt>null</tt> if there is no attachment
396+ */
397+ public final Object attachment() {
398+ return attachment;
399+ }
400+
401+}
java/pkg/java/nio/channels/Selector.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/Selector.java+396−0
@@ -0,0 +1,396 @@
1+/*
2+ * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.Closeable;
29+import java.io.IOException;
30+import java.nio.channels.spi.SelectorProvider;
31+import java.util.Set;
32+
33+
34+/**
35+ * A multiplexor of {@link SelectableChannel} objects.
36+ *
37+ * <p> A selector may be created by invoking the {@link #open open} method of
38+ * this class, which will use the system's default {@link
39+ * java.nio.channels.spi.SelectorProvider </code>selector provider<code>} to
40+ * create a new selector. A selector may also be created by invoking the
41+ * {@link java.nio.channels.spi.SelectorProvider#openSelector openSelector}
42+ * method of a custom selector provider. A selector remains open until it is
43+ * closed via its {@link #close close} method.
44+ *
45+ * <a name="ks">
46+ *
47+ * <p> A selectable channel's registration with a selector is represented by a
48+ * {@link SelectionKey} object. A selector maintains three sets of selection
49+ * keys:
50+ *
51+ * <ul>
52+ *
53+ * <li><p> The <i>key set</i> contains the keys representing the current
54+ * channel registrations of this selector. This set is returned by the
55+ * {@link #keys() keys} method. </p></li>
56+ *
57+ * <li><p> The <i>selected-key set</i> is the set of keys such that each
58+ * key's channel was detected to be ready for at least one of the operations
59+ * identified in the key's interest set during a prior selection operation.
60+ * This set is returned by the {@link #selectedKeys() selectedKeys} method.
61+ * The selected-key set is always a subset of the key set. </p></li>
62+ *
63+ * <li><p> The <i>cancelled-key</i> set is the set of keys that have been
64+ * cancelled but whose channels have not yet been deregistered. This set is
65+ * not directly accessible. The cancelled-key set is always a subset of the
66+ * key set. </p></li>
67+ *
68+ * </ul>
69+ *
70+ * <p> All three sets are empty in a newly-created selector.
71+ *
72+ * <p> A key is added to a selector's key set as a side effect of registering a
73+ * channel via the channel's {@link SelectableChannel#register(Selector,int)
74+ * register} method. Cancelled keys are removed from the key set during
75+ * selection operations. The key set itself is not directly modifiable.
76+ *
77+ * <p> A key is added to its selector's cancelled-key set when it is cancelled,
78+ * whether by closing its channel or by invoking its {@link SelectionKey#cancel
79+ * cancel} method. Cancelling a key will cause its channel to be deregistered
80+ * during the next selection operation, at which time the key will removed from
81+ * all of the selector's key sets.
82+ *
83+ * <a name="sks"><p> Keys are added to the selected-key set by selection
84+ * operations. A key may be removed directly from the selected-key set by
85+ * invoking the set's {@link java.util.Set#remove(java.lang.Object) remove}
86+ * method or by invoking the {@link java.util.Iterator#remove() remove} method
87+ * of an {@link java.util.Iterator </code>iterator<code>} obtained from the
88+ * set. Keys are never removed from the selected-key set in any other way;
89+ * they are not, in particular, removed as a side effect of selection
90+ * operations. Keys may not be added directly to the selected-key set. </p>
91+ *
92+ *
93+ * <a name="selop">
94+ * <h4>Selection</h4>
95+ *
96+ * <p> During each selection operation, keys may be added to and removed from a
97+ * selector's selected-key set and may be removed from its key and
98+ * cancelled-key sets. Selection is performed by the {@link #select()}, {@link
99+ * #select(long)}, and {@link #selectNow()} methods, and involves three steps:
100+ * </p>
101+ *
102+ * <ol>
103+ *
104+ * <li><p> Each key in the cancelled-key set is removed from each key set of
105+ * which it is a member, and its channel is deregistered. This step leaves
106+ * the cancelled-key set empty. </p></li>
107+ *
108+ * <li><p> The underlying operating system is queried for an update as to the
109+ * readiness of each remaining channel to perform any of the operations
110+ * identified by its key's interest set as of the moment that the selection
111+ * operation began. For a channel that is ready for at least one such
112+ * operation, one of the following two actions is performed: </p>
113+ *
114+ * <ol type=a>
115+ *
116+ * <li><p> If the channel's key is not already in the selected-key set then
117+ * it is added to that set and its ready-operation set is modified to
118+ * identify exactly those operations for which the channel is now reported
119+ * to be ready. Any readiness information previously recorded in the ready
120+ * set is discarded. </p></li>
121+ *
122+ * <li><p> Otherwise the channel's key is already in the selected-key set,
123+ * so its ready-operation set is modified to identify any new operations
124+ * for which the channel is reported to be ready. Any readiness
125+ * information previously recorded in the ready set is preserved; in other
126+ * words, the ready set returned by the underlying system is
127+ * bitwise-disjoined into the key's current ready set. </p></li>
128+ *
129+ * </ol></li>
130+ *
131+ * If all of the keys in the key set at the start of this step have empty
132+ * interest sets then neither the selected-key set nor any of the keys'
133+ * ready-operation sets will be updated.
134+ *
135+ * <li><p> If any keys were added to the cancelled-key set while step (2) was
136+ * in progress then they are processed as in step (1). </p></li>
137+ *
138+ * </ol>
139+ *
140+ * <p> Whether or not a selection operation blocks to wait for one or more
141+ * channels to become ready, and if so for how long, is the only essential
142+ * difference between the three selection methods. </p>
143+ *
144+ *
145+ * <h4>Concurrency</h4>
146+ *
147+ * <p> Selectors are themselves safe for use by multiple concurrent threads;
148+ * their key sets, however, are not.
149+ *
150+ * <p> The selection operations synchronize on the selector itself, on the key
151+ * set, and on the selected-key set, in that order. They also synchronize on
152+ * the cancelled-key set during steps (1) and (3) above.
153+ *
154+ * <p> Changes made to the interest sets of a selector's keys while a
155+ * selection operation is in progress have no effect upon that operation; they
156+ * will be seen by the next selection operation.
157+ *
158+ * <p> Keys may be cancelled and channels may be closed at any time. Hence the
159+ * presence of a key in one or more of a selector's key sets does not imply
160+ * that the key is valid or that its channel is open. Application code should
161+ * be careful to synchronize and check these conditions as necessary if there
162+ * is any possibility that another thread will cancel a key or close a channel.
163+ *
164+ * <p> A thread blocked in one of the {@link #select()} or {@link
165+ * #select(long)} methods may be interrupted by some other thread in one of
166+ * three ways:
167+ *
168+ * <ul>
169+ *
170+ * <li><p> By invoking the selector's {@link #wakeup wakeup} method,
171+ * </p></li>
172+ *
173+ * <li><p> By invoking the selector's {@link #close close} method, or
174+ * </p></li>
175+ *
176+ * <li><p> By invoking the blocked thread's {@link
177+ * java.lang.Thread#interrupt() interrupt} method, in which case its
178+ * interrupt status will be set and the selector's {@link #wakeup wakeup}
179+ * method will be invoked. </p></li>
180+ *
181+ * </ul>
182+ *
183+ * <p> The {@link #close close} method synchronizes on the selector and all
184+ * three key sets in the same order as in a selection operation.
185+ *
186+ * <a name="ksc">
187+ *
188+ * <p> A selector's key and selected-key sets are not, in general, safe for use
189+ * by multiple concurrent threads. If such a thread might modify one of these
190+ * sets directly then access should be controlled by synchronizing on the set
191+ * itself. The iterators returned by these sets' {@link
192+ * java.util.Set#iterator() iterator} methods are <i>fail-fast:</i> If the set
193+ * is modified after the iterator is created, in any way except by invoking the
194+ * iterator's own {@link java.util.Iterator#remove() remove} method, then a
195+ * {@link java.util.ConcurrentModificationException} will be thrown. </p>
196+ *
197+ *
198+ * @author Mark Reinhold
199+ * @author JSR-51 Expert Group
200+ * @since 1.4
201+ *
202+ * @see SelectableChannel
203+ * @see SelectionKey
204+ */
205+
206+public abstract class Selector implements Closeable {
207+
208+ /**
209+ * Initializes a new instance of this class.
210+ */
211+ protected Selector() { }
212+
213+ /**
214+ * Opens a selector.
215+ *
216+ * <p> The new selector is created by invoking the {@link
217+ * java.nio.channels.spi.SelectorProvider#openSelector openSelector} method
218+ * of the system-wide default {@link
219+ * java.nio.channels.spi.SelectorProvider} object. </p>
220+ *
221+ * @return A new selector
222+ *
223+ * @throws IOException
224+ * If an I/O error occurs
225+ */
226+ public static Selector open() throws IOException {
227+ return SelectorProvider.provider().openSelector();
228+ }
229+
230+ /**
231+ * Tells whether or not this selector is open. </p>
232+ *
233+ * @return <tt>true</tt> if, and only if, this selector is open
234+ */
235+ public abstract boolean isOpen();
236+
237+ /**
238+ * Returns the provider that created this channel. </p>
239+ *
240+ * @return The provider that created this channel
241+ */
242+ public abstract SelectorProvider provider();
243+
244+ /**
245+ * Returns this selector's key set.
246+ *
247+ * <p> The key set is not directly modifiable. A key is removed only after
248+ * it has been cancelled and its channel has been deregistered. Any
249+ * attempt to modify the key set will cause an {@link
250+ * UnsupportedOperationException} to be thrown.
251+ *
252+ * <p> The key set is <a href="#ksc">not thread-safe</a>. </p>
253+ *
254+ * @return This selector's key set
255+ *
256+ * @throws ClosedSelectorException
257+ * If this selector is closed
258+ */
259+ public abstract Set<SelectionKey> keys();
260+
261+ /**
262+ * Returns this selector's selected-key set.
263+ *
264+ * <p> Keys may be removed from, but not directly added to, the
265+ * selected-key set. Any attempt to add an object to the key set will
266+ * cause an {@link UnsupportedOperationException} to be thrown.
267+ *
268+ * <p> The selected-key set is <a href="#ksc">not thread-safe</a>. </p>
269+ *
270+ * @return This selector's selected-key set
271+ *
272+ * @throws ClosedSelectorException
273+ * If this selector is closed
274+ */
275+ public abstract Set<SelectionKey> selectedKeys();
276+
277+ /**
278+ * Selects a set of keys whose corresponding channels are ready for I/O
279+ * operations.
280+ *
281+ * <p> This method performs a non-blocking <a href="#selop">selection
282+ * operation</a>. If no channels have become selectable since the previous
283+ * selection operation then this method immediately returns zero.
284+ *
285+ * <p> Invoking this method clears the effect of any previous invocations
286+ * of the {@link #wakeup wakeup} method. </p>
287+ *
288+ * @return The number of keys, possibly zero, whose ready-operation sets
289+ * were updated by the selection operation
290+ *
291+ * @throws IOException
292+ * If an I/O error occurs
293+ *
294+ * @throws ClosedSelectorException
295+ * If this selector is closed
296+ */
297+ public abstract int selectNow() throws IOException;
298+
299+ /**
300+ * Selects a set of keys whose corresponding channels are ready for I/O
301+ * operations.
302+ *
303+ * <p> This method performs a blocking <a href="#selop">selection
304+ * operation</a>. It returns only after at least one channel is selected,
305+ * this selector's {@link #wakeup wakeup} method is invoked, the current
306+ * thread is interrupted, or the given timeout period expires, whichever
307+ * comes first.
308+ *
309+ * <p> This method does not offer real-time guarantees: It schedules the
310+ * timeout as if by invoking the {@link Object#wait(long)} method. </p>
311+ *
312+ * @param timeout If positive, block for up to <tt>timeout</tt>
313+ * milliseconds, more or less, while waiting for a
314+ * channel to become ready; if zero, block indefinitely;
315+ * must not be negative
316+ *
317+ * @return The number of keys, possibly zero,
318+ * whose ready-operation sets were updated
319+ *
320+ * @throws IOException
321+ * If an I/O error occurs
322+ *
323+ * @throws ClosedSelectorException
324+ * If this selector is closed
325+ *
326+ * @throws IllegalArgumentException
327+ * If the value of the timeout argument is negative
328+ */
329+ public abstract int select(long timeout)
330+ throws IOException;
331+
332+ /**
333+ * Selects a set of keys whose corresponding channels are ready for I/O
334+ * operations.
335+ *
336+ * <p> This method performs a blocking <a href="#selop">selection
337+ * operation</a>. It returns only after at least one channel is selected,
338+ * this selector's {@link #wakeup wakeup} method is invoked, or the current
339+ * thread is interrupted, whichever comes first. </p>
340+ *
341+ * @return The number of keys, possibly zero,
342+ * whose ready-operation sets were updated
343+ *
344+ * @throws IOException
345+ * If an I/O error occurs
346+ *
347+ * @throws ClosedSelectorException
348+ * If this selector is closed
349+ */
350+ public abstract int select() throws IOException;
351+
352+ /**
353+ * Causes the first selection operation that has not yet returned to return
354+ * immediately.
355+ *
356+ * <p> If another thread is currently blocked in an invocation of the
357+ * {@link #select()} or {@link #select(long)} methods then that invocation
358+ * will return immediately. If no selection operation is currently in
359+ * progress then the next invocation of one of these methods will return
360+ * immediately unless the {@link #selectNow()} method is invoked in the
361+ * meantime. In any case the value returned by that invocation may be
362+ * non-zero. Subsequent invocations of the {@link #select()} or {@link
363+ * #select(long)} methods will block as usual unless this method is invoked
364+ * again in the meantime.
365+ *
366+ * <p> Invoking this method more than once between two successive selection
367+ * operations has the same effect as invoking it just once. </p>
368+ *
369+ * @return This selector
370+ */
371+ public abstract Selector wakeup();
372+
373+ /**
374+ * Closes this selector.
375+ *
376+ * <p> If a thread is currently blocked in one of this selector's selection
377+ * methods then it is interrupted as if by invoking the selector's {@link
378+ * #wakeup wakeup} method.
379+ *
380+ * <p> Any uncancelled keys still associated with this selector are
381+ * invalidated, their channels are deregistered, and any other resources
382+ * associated with this selector are released.
383+ *
384+ * <p> If this selector is already closed then invoking this method has no
385+ * effect.
386+ *
387+ * <p> After a selector is closed, any further attempt to use it, except by
388+ * invoking this method or the {@link #wakeup wakeup} method, will cause a
389+ * {@link ClosedSelectorException} to be thrown. </p>
390+ *
391+ * @throws IOException
392+ * If an I/O error occurs
393+ */
394+ public abstract void close() throws IOException;
395+
396+}
java/pkg/java/nio/channels/ServerSocketChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/ServerSocketChannel.java+268−0
@@ -0,0 +1,268 @@
1+/*
2+ * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.net.ServerSocket;
30+import java.net.SocketOption;
31+import java.net.SocketAddress;
32+import java.nio.channels.spi.AbstractSelectableChannel;
33+import java.nio.channels.spi.SelectorProvider;
34+
35+/**
36+ * A selectable channel for stream-oriented listening sockets.
37+ *
38+ * <p> A server-socket channel is created by invoking the {@link #open() open}
39+ * method of this class. It is not possible to create a channel for an arbitrary,
40+ * pre-existing {@link ServerSocket}. A newly-created server-socket channel is
41+ * open but not yet bound. An attempt to invoke the {@link #accept() accept}
42+ * method of an unbound server-socket channel will cause a {@link NotYetBoundException}
43+ * to be thrown. A server-socket channel can be bound by invoking one of the
44+ * {@link #bind(java.net.SocketAddress,int) bind} methods defined by this class.
45+ *
46+ * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
47+ * setOption} method. Server-socket channels support the following options:
48+ * <blockquote>
49+ * <table border>
50+ * <tr>
51+ * <th>Option Name</th>
52+ * <th>Description</th>
53+ * </tr>
54+ * <tr>
55+ * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
56+ * <td> The size of the socket receive buffer </td>
57+ * </tr>
58+ * <tr>
59+ * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
60+ * <td> Re-use address </td>
61+ * </tr>
62+ * </table>
63+ * </blockquote>
64+ * Additional (implementation specific) options may also be supported.
65+ *
66+ * <p> Server-socket channels are safe for use by multiple concurrent threads.
67+ * </p>
68+ *
69+ * @author Mark Reinhold
70+ * @author JSR-51 Expert Group
71+ * @since 1.4
72+ */
73+
74+public abstract class ServerSocketChannel
75+ extends AbstractSelectableChannel
76+ implements NetworkChannel
77+{
78+
79+ /**
80+ * Initializes a new instance of this class.
81+ */
82+ protected ServerSocketChannel(SelectorProvider provider) {
83+ super(provider);
84+ }
85+
86+ /**
87+ * Opens a server-socket channel.
88+ *
89+ * <p> The new channel is created by invoking the {@link
90+ * java.nio.channels.spi.SelectorProvider#openServerSocketChannel
91+ * openServerSocketChannel} method of the system-wide default {@link
92+ * java.nio.channels.spi.SelectorProvider} object.
93+ *
94+ * <p> The new channel's socket is initially unbound; it must be bound to a
95+ * specific address via one of its socket's {@link
96+ * java.net.ServerSocket#bind(SocketAddress) bind} methods before
97+ * connections can be accepted. </p>
98+ *
99+ * @return A new socket channel
100+ *
101+ * @throws IOException
102+ * If an I/O error occurs
103+ */
104+ public static ServerSocketChannel open() throws IOException {
105+ return SelectorProvider.provider().openServerSocketChannel();
106+ }
107+
108+ /**
109+ * Returns an operation set identifying this channel's supported
110+ * operations.
111+ *
112+ * <p> Server-socket channels only support the accepting of new
113+ * connections, so this method returns {@link SelectionKey#OP_ACCEPT}.
114+ * </p>
115+ *
116+ * @return The valid-operation set
117+ */
118+ public final int validOps() {
119+ return SelectionKey.OP_ACCEPT;
120+ }
121+
122+
123+ // -- ServerSocket-specific operations --
124+
125+ /**
126+ * Binds the channel's socket to a local address and configures the socket
127+ * to listen for connections.
128+ *
129+ * <p> An invocation of this method is equivalent to the following:
130+ * <blockquote><pre>
131+ * bind(local, 0);
132+ * </pre></blockquote>
133+ *
134+ * @param local
135+ * The local address to bind the socket, or {@code null} to bind
136+ * to an automatically assigned socket address
137+ *
138+ * @return This channel
139+ *
140+ * @throws AlreadyBoundException {@inheritDoc}
141+ * @throws UnsupportedAddressTypeException {@inheritDoc}
142+ * @throws ClosedChannelException {@inheritDoc}
143+ * @throws IOException {@inheritDoc}
144+ * @throws SecurityException
145+ * If a security manager has been installed and its {@link
146+ * SecurityManager#checkListen checkListen} method denies the
147+ * operation
148+ *
149+ * @since 1.7
150+ */
151+ public final ServerSocketChannel bind(SocketAddress local)
152+ throws IOException
153+ {
154+ return bind(local, 0);
155+ }
156+
157+ /**
158+ * Binds the channel's socket to a local address and configures the socket to
159+ * listen for connections.
160+ *
161+ * <p> This method is used to establish an association between the socket and
162+ * a local address. Once an association is established then the socket remains
163+ * bound until the channel is closed.
164+ *
165+ * <p> The {@code backlog} parameter is the maximum number of pending
166+ * connections on the socket. Its exact semantics are implementation specific.
167+ * In particular, an implementation may impose a maximum length or may choose
168+ * to ignore the parameter altogther. If the {@code backlog} parameter has
169+ * the value {@code 0}, or a negative value, then an implementation specific
170+ * default is used.
171+ *
172+ * @param local
173+ * The address to bind the socket, or {@code null} to bind to an
174+ * automatically assigned socket address
175+ * @param backlog
176+ * The maximum number of pending connections
177+ *
178+ * @return This channel
179+ *
180+ * @throws AlreadyBoundException
181+ * If the socket is already bound
182+ * @throws UnsupportedAddressTypeException
183+ * If the type of the given address is not supported
184+ * @throws ClosedChannelException
185+ * If this channel is closed
186+ * @throws IOException
187+ * If some other I/O error occurs
188+ * @throws SecurityException
189+ * If a security manager has been installed and its {@link
190+ * SecurityManager#checkListen checkListen} method denies the
191+ * operation
192+ *
193+ * @since 1.7
194+ */
195+ public abstract ServerSocketChannel bind(SocketAddress local, int backlog)
196+ throws IOException;
197+
198+ /**
199+ * @throws UnsupportedOperationException {@inheritDoc}
200+ * @throws IllegalArgumentException {@inheritDoc}
201+ * @throws ClosedChannelException {@inheritDoc}
202+ * @throws IOException {@inheritDoc}
203+ *
204+ * @since 1.7
205+ */
206+ public abstract <T> ServerSocketChannel setOption(SocketOption<T> name, T value)
207+ throws IOException;
208+
209+ /**
210+ * Retrieves a server socket associated with this channel.
211+ *
212+ * <p> The returned object will not declare any public methods that are not
213+ * declared in the {@link java.net.ServerSocket} class. </p>
214+ *
215+ * @return A server socket associated with this channel
216+ */
217+ public abstract ServerSocket socket();
218+
219+ /**
220+ * Accepts a connection made to this channel's socket.
221+ *
222+ * <p> If this channel is in non-blocking mode then this method will
223+ * immediately return <tt>null</tt> if there are no pending connections.
224+ * Otherwise it will block indefinitely until a new connection is available
225+ * or an I/O error occurs.
226+ *
227+ * <p> The socket channel returned by this method, if any, will be in
228+ * blocking mode regardless of the blocking mode of this channel.
229+ *
230+ * <p> This method performs exactly the same security checks as the {@link
231+ * java.net.ServerSocket#accept accept} method of the {@link
232+ * java.net.ServerSocket} class. That is, if a security manager has been
233+ * installed then for each new connection this method verifies that the
234+ * address and port number of the connection's remote endpoint are
235+ * permitted by the security manager's {@link
236+ * java.lang.SecurityManager#checkAccept checkAccept} method. </p>
237+ *
238+ * @return The socket channel for the new connection,
239+ * or <tt>null</tt> if this channel is in non-blocking mode
240+ * and no connection is available to be accepted
241+ *
242+ * @throws ClosedChannelException
243+ * If this channel is closed
244+ *
245+ * @throws AsynchronousCloseException
246+ * If another thread closes this channel
247+ * while the accept operation is in progress
248+ *
249+ * @throws ClosedByInterruptException
250+ * If another thread interrupts the current thread
251+ * while the accept operation is in progress, thereby
252+ * closing the channel and setting the current thread's
253+ * interrupt status
254+ *
255+ * @throws NotYetBoundException
256+ * If this channel's socket has not yet been bound
257+ *
258+ * @throws SecurityException
259+ * If a security manager has been installed
260+ * and it does not permit access to the remote endpoint
261+ * of the new connection
262+ *
263+ * @throws IOException
264+ * If some other I/O error occurs
265+ */
266+ public abstract SocketChannel accept() throws IOException;
267+
268+}
java/pkg/java/nio/channels/SocketChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/SocketChannel.java+496−0
@@ -0,0 +1,496 @@
1+/*
2+ * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.net.Socket;
30+import java.net.SocketOption;
31+import java.net.SocketAddress;
32+import java.nio.ByteBuffer;
33+import java.nio.channels.spi.AbstractSelectableChannel;
34+import java.nio.channels.spi.SelectorProvider;
35+
36+/**
37+ * A selectable channel for stream-oriented connecting sockets.
38+ *
39+ * <p> A socket channel is created by invoking one of the {@link #open open}
40+ * methods of this class. It is not possible to create a channel for an arbitrary,
41+ * pre-existing socket. A newly-created socket channel is open but not yet
42+ * connected. An attempt to invoke an I/O operation upon an unconnected
43+ * channel will cause a {@link NotYetConnectedException} to be thrown. A
44+ * socket channel can be connected by invoking its {@link #connect connect}
45+ * method; once connected, a socket channel remains connected until it is
46+ * closed. Whether or not a socket channel is connected may be determined by
47+ * invoking its {@link #isConnected isConnected} method.
48+ *
49+ * <p> Socket channels support <i>non-blocking connection:</i>&nbsp;A socket
50+ * channel may be created and the process of establishing the link to the
51+ * remote socket may be initiated via the {@link #connect connect} method for
52+ * later completion by the {@link #finishConnect finishConnect} method.
53+ * Whether or not a connection operation is in progress may be determined by
54+ * invoking the {@link #isConnectionPending isConnectionPending} method.
55+ *
56+ * <p> Socket channels support <i>asynchronous shutdown,</i> which is similar
57+ * to the asynchronous close operation specified in the {@link Channel} class.
58+ * If the input side of a socket is shut down by one thread while another
59+ * thread is blocked in a read operation on the socket's channel, then the read
60+ * operation in the blocked thread will complete without reading any bytes and
61+ * will return <tt>-1</tt>. If the output side of a socket is shut down by one
62+ * thread while another thread is blocked in a write operation on the socket's
63+ * channel, then the blocked thread will receive an {@link
64+ * AsynchronousCloseException}.
65+ *
66+ * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
67+ * setOption} method. Socket channels support the following options:
68+ * <blockquote>
69+ * <table border>
70+ * <tr>
71+ * <th>Option Name</th>
72+ * <th>Description</th>
73+ * </tr>
74+ * <tr>
75+ * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td>
76+ * <td> The size of the socket send buffer </td>
77+ * </tr>
78+ * <tr>
79+ * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
80+ * <td> The size of the socket receive buffer </td>
81+ * </tr>
82+ * <tr>
83+ * <td> {@link java.net.StandardSocketOptions#SO_KEEPALIVE SO_KEEPALIVE} </td>
84+ * <td> Keep connection alive </td>
85+ * </tr>
86+ * <tr>
87+ * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
88+ * <td> Re-use address </td>
89+ * </tr>
90+ * <tr>
91+ * <td> {@link java.net.StandardSocketOptions#SO_LINGER SO_LINGER} </td>
92+ * <td> Linger on close if data is present (when configured in blocking mode
93+ * only) </td>
94+ * </tr>
95+ * <tr>
96+ * <td> {@link java.net.StandardSocketOptions#TCP_NODELAY TCP_NODELAY} </td>
97+ * <td> Disable the Nagle algorithm </td>
98+ * </tr>
99+ * </table>
100+ * </blockquote>
101+ * Additional (implementation specific) options may also be supported.
102+ *
103+ * <p> Socket channels are safe for use by multiple concurrent threads. They
104+ * support concurrent reading and writing, though at most one thread may be
105+ * reading and at most one thread may be writing at any given time. The {@link
106+ * #connect connect} and {@link #finishConnect finishConnect} methods are
107+ * mutually synchronized against each other, and an attempt to initiate a read
108+ * or write operation while an invocation of one of these methods is in
109+ * progress will block until that invocation is complete. </p>
110+ *
111+ * @author Mark Reinhold
112+ * @author JSR-51 Expert Group
113+ * @since 1.4
114+ */
115+
116+public abstract class SocketChannel
117+ extends AbstractSelectableChannel
118+ implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, NetworkChannel
119+{
120+
121+ /**
122+ * Initializes a new instance of this class.
123+ */
124+ protected SocketChannel(SelectorProvider provider) {
125+ super(provider);
126+ }
127+
128+ /**
129+ * Opens a socket channel.
130+ *
131+ * <p> The new channel is created by invoking the {@link
132+ * java.nio.channels.spi.SelectorProvider#openSocketChannel
133+ * openSocketChannel} method of the system-wide default {@link
134+ * java.nio.channels.spi.SelectorProvider} object. </p>
135+ *
136+ * @return A new socket channel
137+ *
138+ * @throws IOException
139+ * If an I/O error occurs
140+ */
141+ public static SocketChannel open() throws IOException {
142+ return SelectorProvider.provider().openSocketChannel();
143+ }
144+
145+ /**
146+ * Opens a socket channel and connects it to a remote address.
147+ *
148+ * <p> This convenience method works as if by invoking the {@link #open()}
149+ * method, invoking the {@link #connect(SocketAddress) connect} method upon
150+ * the resulting socket channel, passing it <tt>remote</tt>, and then
151+ * returning that channel. </p>
152+ *
153+ * @param remote
154+ * The remote address to which the new channel is to be connected
155+ *
156+ * @throws AsynchronousCloseException
157+ * If another thread closes this channel
158+ * while the connect operation is in progress
159+ *
160+ * @throws ClosedByInterruptException
161+ * If another thread interrupts the current thread
162+ * while the connect operation is in progress, thereby
163+ * closing the channel and setting the current thread's
164+ * interrupt status
165+ *
166+ * @throws UnresolvedAddressException
167+ * If the given remote address is not fully resolved
168+ *
169+ * @throws UnsupportedAddressTypeException
170+ * If the type of the given remote address is not supported
171+ *
172+ * @throws SecurityException
173+ * If a security manager has been installed
174+ * and it does not permit access to the given remote endpoint
175+ *
176+ * @throws IOException
177+ * If some other I/O error occurs
178+ */
179+ public static SocketChannel open(SocketAddress remote)
180+ throws IOException
181+ {
182+ SocketChannel sc = open();
183+ try {
184+ sc.connect(remote);
185+ } catch (Throwable x) {
186+ try {
187+ sc.close();
188+ } catch (Throwable suppressed) {
189+ x.addSuppressed(suppressed);
190+ }
191+ throw x;
192+ }
193+ assert sc.isConnected();
194+ return sc;
195+ }
196+
197+ /**
198+ * Returns an operation set identifying this channel's supported
199+ * operations.
200+ *
201+ * <p> Socket channels support connecting, reading, and writing, so this
202+ * method returns <tt>(</tt>{@link SelectionKey#OP_CONNECT}
203+ * <tt>|</tt>&nbsp;{@link SelectionKey#OP_READ} <tt>|</tt>&nbsp;{@link
204+ * SelectionKey#OP_WRITE}<tt>)</tt>. </p>
205+ *
206+ * @return The valid-operation set
207+ */
208+ public final int validOps() {
209+ return (SelectionKey.OP_READ
210+ | SelectionKey.OP_WRITE
211+ | SelectionKey.OP_CONNECT);
212+ }
213+
214+
215+ // -- Socket-specific operations --
216+
217+ /**
218+ * @throws ConnectionPendingException
219+ * If a non-blocking connect operation is already in progress on
220+ * this channel
221+ * @throws AlreadyBoundException {@inheritDoc}
222+ * @throws UnsupportedAddressTypeException {@inheritDoc}
223+ * @throws ClosedChannelException {@inheritDoc}
224+ * @throws IOException {@inheritDoc}
225+ *
226+ * @since 1.7
227+ */
228+ @Override
229+ public abstract SocketChannel bind(SocketAddress local)
230+ throws IOException;
231+
232+ /**
233+ * @throws UnsupportedOperationException {@inheritDoc}
234+ * @throws IllegalArgumentException {@inheritDoc}
235+ * @throws ClosedChannelException {@inheritDoc}
236+ * @throws IOException {@inheritDoc}
237+ *
238+ * @since 1.7
239+ */
240+ @Override
241+ public abstract <T> SocketChannel setOption(SocketOption<T> name, T value)
242+ throws IOException;
243+
244+ /**
245+ * Shutdown the connection for reading without closing the channel.
246+ *
247+ * <p> Once shutdown for reading then further reads on the channel will
248+ * return {@code -1}, the end-of-stream indication. If the input side of the
249+ * connection is already shutdown then invoking this method has no effect.
250+ *
251+ * @return The channel
252+ *
253+ * @throws NotYetConnectedException
254+ * If this channel is not yet connected
255+ * @throws ClosedChannelException
256+ * If this channel is closed
257+ * @throws IOException
258+ * If some other I/O error occurs
259+ *
260+ * @since 1.7
261+ */
262+ public abstract SocketChannel shutdownInput() throws IOException;
263+
264+ /**
265+ * Shutdown the connection for writing without closing the channel.
266+ *
267+ * <p> Once shutdown for writing then further attempts to write to the
268+ * channel will throw {@link ClosedChannelException}. If the output side of
269+ * the connection is already shutdown then invoking this method has no
270+ * effect.
271+ *
272+ * @return The channel
273+ *
274+ * @throws NotYetConnectedException
275+ * If this channel is not yet connected
276+ * @throws ClosedChannelException
277+ * If this channel is closed
278+ * @throws IOException
279+ * If some other I/O error occurs
280+ *
281+ * @since 1.7
282+ */
283+ public abstract SocketChannel shutdownOutput() throws IOException;
284+
285+ /**
286+ * Retrieves a socket associated with this channel.
287+ *
288+ * <p> The returned object will not declare any public methods that are not
289+ * declared in the {@link java.net.Socket} class. </p>
290+ *
291+ * @return A socket associated with this channel
292+ */
293+ public abstract Socket socket();
294+
295+ /**
296+ * Tells whether or not this channel's network socket is connected.
297+ *
298+ * @return <tt>true</tt> if, and only if, this channel's network socket
299+ * is {@link #isOpen open} and connected
300+ */
301+ public abstract boolean isConnected();
302+
303+ /**
304+ * Tells whether or not a connection operation is in progress on this
305+ * channel. </p>
306+ *
307+ * @return <tt>true</tt> if, and only if, a connection operation has been
308+ * initiated on this channel but not yet completed by invoking the
309+ * {@link #finishConnect finishConnect} method
310+ */
311+ public abstract boolean isConnectionPending();
312+
313+ /**
314+ * Connects this channel's socket.
315+ *
316+ * <p> If this channel is in non-blocking mode then an invocation of this
317+ * method initiates a non-blocking connection operation. If the connection
318+ * is established immediately, as can happen with a local connection, then
319+ * this method returns <tt>true</tt>. Otherwise this method returns
320+ * <tt>false</tt> and the connection operation must later be completed by
321+ * invoking the {@link #finishConnect finishConnect} method.
322+ *
323+ * <p> If this channel is in blocking mode then an invocation of this
324+ * method will block until the connection is established or an I/O error
325+ * occurs.
326+ *
327+ * <p> This method performs exactly the same security checks as the {@link
328+ * java.net.Socket} class. That is, if a security manager has been
329+ * installed then this method verifies that its {@link
330+ * java.lang.SecurityManager#checkConnect checkConnect} method permits
331+ * connecting to the address and port number of the given remote endpoint.
332+ *
333+ * <p> This method may be invoked at any time. If a read or write
334+ * operation upon this channel is invoked while an invocation of this
335+ * method is in progress then that operation will first block until this
336+ * invocation is complete. If a connection attempt is initiated but fails,
337+ * that is, if an invocation of this method throws a checked exception,
338+ * then the channel will be closed. </p>
339+ *
340+ * @param remote
341+ * The remote address to which this channel is to be connected
342+ *
343+ * @return <tt>true</tt> if a connection was established,
344+ * <tt>false</tt> if this channel is in non-blocking mode
345+ * and the connection operation is in progress
346+ *
347+ * @throws AlreadyConnectedException
348+ * If this channel is already connected
349+ *
350+ * @throws ConnectionPendingException
351+ * If a non-blocking connection operation is already in progress
352+ * on this channel
353+ *
354+ * @throws ClosedChannelException
355+ * If this channel is closed
356+ *
357+ * @throws AsynchronousCloseException
358+ * If another thread closes this channel
359+ * while the connect operation is in progress
360+ *
361+ * @throws ClosedByInterruptException
362+ * If another thread interrupts the current thread
363+ * while the connect operation is in progress, thereby
364+ * closing the channel and setting the current thread's
365+ * interrupt status
366+ *
367+ * @throws UnresolvedAddressException
368+ * If the given remote address is not fully resolved
369+ *
370+ * @throws UnsupportedAddressTypeException
371+ * If the type of the given remote address is not supported
372+ *
373+ * @throws SecurityException
374+ * If a security manager has been installed
375+ * and it does not permit access to the given remote endpoint
376+ *
377+ * @throws IOException
378+ * If some other I/O error occurs
379+ */
380+ public abstract boolean connect(SocketAddress remote) throws IOException;
381+
382+ /**
383+ * Finishes the process of connecting a socket channel.
384+ *
385+ * <p> A non-blocking connection operation is initiated by placing a socket
386+ * channel in non-blocking mode and then invoking its {@link #connect
387+ * connect} method. Once the connection is established, or the attempt has
388+ * failed, the socket channel will become connectable and this method may
389+ * be invoked to complete the connection sequence. If the connection
390+ * operation failed then invoking this method will cause an appropriate
391+ * {@link java.io.IOException} to be thrown.
392+ *
393+ * <p> If this channel is already connected then this method will not block
394+ * and will immediately return <tt>true</tt>. If this channel is in
395+ * non-blocking mode then this method will return <tt>false</tt> if the
396+ * connection process is not yet complete. If this channel is in blocking
397+ * mode then this method will block until the connection either completes
398+ * or fails, and will always either return <tt>true</tt> or throw a checked
399+ * exception describing the failure.
400+ *
401+ * <p> This method may be invoked at any time. If a read or write
402+ * operation upon this channel is invoked while an invocation of this
403+ * method is in progress then that operation will first block until this
404+ * invocation is complete. If a connection attempt fails, that is, if an
405+ * invocation of this method throws a checked exception, then the channel
406+ * will be closed. </p>
407+ *
408+ * @return <tt>true</tt> if, and only if, this channel's socket is now
409+ * connected
410+ *
411+ * @throws NoConnectionPendingException
412+ * If this channel is not connected and a connection operation
413+ * has not been initiated
414+ *
415+ * @throws ClosedChannelException
416+ * If this channel is closed
417+ *
418+ * @throws AsynchronousCloseException
419+ * If another thread closes this channel
420+ * while the connect operation is in progress
421+ *
422+ * @throws ClosedByInterruptException
423+ * If another thread interrupts the current thread
424+ * while the connect operation is in progress, thereby
425+ * closing the channel and setting the current thread's
426+ * interrupt status
427+ *
428+ * @throws IOException
429+ * If some other I/O error occurs
430+ */
431+ public abstract boolean finishConnect() throws IOException;
432+
433+ /**
434+ * Returns the remote address to which this channel's socket is connected.
435+ *
436+ * <p> Where the channel is bound and connected to an Internet Protocol
437+ * socket address then the return value from this method is of type {@link
438+ * java.net.InetSocketAddress}.
439+ *
440+ * @return The remote address; {@code null} if the channel's socket is not
441+ * connected
442+ *
443+ * @throws ClosedChannelException
444+ * If the channel is closed
445+ * @throws IOException
446+ * If an I/O error occurs
447+ *
448+ * @since 1.7
449+ */
450+ public abstract SocketAddress getRemoteAddress() throws IOException;
451+
452+ // -- ByteChannel operations --
453+
454+ /**
455+ * @throws NotYetConnectedException
456+ * If this channel is not yet connected
457+ */
458+ public abstract int read(ByteBuffer dst) throws IOException;
459+
460+ /**
461+ * @throws NotYetConnectedException
462+ * If this channel is not yet connected
463+ */
464+ public abstract long read(ByteBuffer[] dsts, int offset, int length)
465+ throws IOException;
466+
467+ /**
468+ * @throws NotYetConnectedException
469+ * If this channel is not yet connected
470+ */
471+ public final long read(ByteBuffer[] dsts) throws IOException {
472+ return read(dsts, 0, dsts.length);
473+ }
474+
475+ /**
476+ * @throws NotYetConnectedException
477+ * If this channel is not yet connected
478+ */
479+ public abstract int write(ByteBuffer src) throws IOException;
480+
481+ /**
482+ * @throws NotYetConnectedException
483+ * If this channel is not yet connected
484+ */
485+ public abstract long write(ByteBuffer[] srcs, int offset, int length)
486+ throws IOException;
487+
488+ /**
489+ * @throws NotYetConnectedException
490+ * If this channel is not yet connected
491+ */
492+ public final long write(ByteBuffer[] srcs) throws IOException {
493+ return write(srcs, 0, srcs.length);
494+ }
495+
496+}
java/pkg/java/nio/channels/WritableByteChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/WritableByteChannel.java+105−0
@@ -0,0 +1,105 @@
1+/*
2+ * Copyright (c) 2000, 2005, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels;
27+
28+import java.io.IOException;
29+import java.nio.ByteBuffer;
30+
31+
32+/**
33+ * A channel that can write bytes.
34+ *
35+ * <p> Only one write operation upon a writable channel may be in progress at
36+ * any given time. If one thread initiates a write operation upon a channel
37+ * then any other thread that attempts to initiate another write operation will
38+ * block until the first operation is complete. Whether or not other kinds of
39+ * I/O operations may proceed concurrently with a write operation depends upon
40+ * the type of the channel. </p>
41+ *
42+ *
43+ * @author Mark Reinhold
44+ * @author JSR-51 Expert Group
45+ * @since 1.4
46+ */
47+
48+public interface WritableByteChannel
49+ extends Channel
50+{
51+
52+ /**
53+ * Writes a sequence of bytes to this channel from the given buffer.
54+ *
55+ * <p> An attempt is made to write up to <i>r</i> bytes to the channel,
56+ * where <i>r</i> is the number of bytes remaining in the buffer, that is,
57+ * <tt>src.remaining()</tt>, at the moment this method is invoked.
58+ *
59+ * <p> Suppose that a byte sequence of length <i>n</i> is written, where
60+ * <tt>0</tt>&nbsp;<tt>&lt;=</tt>&nbsp;<i>n</i>&nbsp;<tt>&lt;=</tt>&nbsp;<i>r</i>.
61+ * This byte sequence will be transferred from the buffer starting at index
62+ * <i>p</i>, where <i>p</i> is the buffer's position at the moment this
63+ * method is invoked; the index of the last byte written will be
64+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>&nbsp;<tt>-</tt>&nbsp;<tt>1</tt>.
65+ * Upon return the buffer's position will be equal to
66+ * <i>p</i>&nbsp;<tt>+</tt>&nbsp;<i>n</i>; its limit will not have changed.
67+ *
68+ * <p> Unless otherwise specified, a write operation will return only after
69+ * writing all of the <i>r</i> requested bytes. Some types of channels,
70+ * depending upon their state, may write only some of the bytes or possibly
71+ * none at all. A socket channel in non-blocking mode, for example, cannot
72+ * write any more bytes than are free in the socket's output buffer.
73+ *
74+ * <p> This method may be invoked at any time. If another thread has
75+ * already initiated a write operation upon this channel, however, then an
76+ * invocation of this method will block until the first operation is
77+ * complete. </p>
78+ *
79+ * @param src
80+ * The buffer from which bytes are to be retrieved
81+ *
82+ * @return The number of bytes written, possibly zero
83+ *
84+ * @throws NonWritableChannelException
85+ * If this channel was not opened for writing
86+ *
87+ * @throws ClosedChannelException
88+ * If this channel is closed
89+ *
90+ * @throws AsynchronousCloseException
91+ * If another thread closes this channel
92+ * while the write operation is in progress
93+ *
94+ * @throws ClosedByInterruptException
95+ * If another thread interrupts the current thread
96+ * while the write operation is in progress, thereby
97+ * closing the channel and setting the current thread's
98+ * interrupt status
99+ *
100+ * @throws IOException
101+ * If some other I/O error occurs
102+ */
103+ public int write(ByteBuffer src) throws IOException;
104+
105+}
java/pkg/java/nio/channels/exceptions+194−0
@@ -0,0 +1,194 @@
1+#
2+# Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+#
5+# This code is free software; you can redistribute it and/or modify it
6+# under the terms of the GNU General Public License version 2 only, as
7+# published by the Free Software Foundation. Oracle designates this
8+# particular file as subject to the "Classpath" exception as provided
9+# by Oracle in the LICENSE file that accompanied this code.
10+#
11+# This code is distributed in the hope that it will be useful, but WITHOUT
12+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+# version 2 for more details (a copy is included in the LICENSE file that
15+# accompanied this code).
16+#
17+# You should have received a copy of the GNU General Public License version
18+# 2 along with this work; if not, write to the Free Software Foundation,
19+# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+#
21+# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+# or visit www.oracle.com if you need additional information or have any
23+# questions.
24+#
25+
26+# Generated exception classes for java.nio.channels
27+
28+SINCE=1.4
29+PACKAGE=java.nio.channels
30+# This year should only change if the generated source is modified.
31+COPYRIGHT_YEARS="2000, 2007,"
32+
33+
34+SUPER=java.io.IOException
35+
36+gen ClosedChannelException "
37+ * Checked exception thrown when an attempt is made to invoke or complete an
38+ * I/O operation upon channel that is closed, or at least closed to that
39+ * operation. That this exception is thrown does not necessarily imply that
40+ * the channel is completely closed. A socket channel whose write half has
41+ * been shut down, for example, may still be open for reading." \
42+ 882777185433553857L
43+
44+gen FileLockInterruptionException "
45+ * Checked exception received by a thread when another thread interrupts it
46+ * while it is waiting to acquire a file lock. Before this exception is thrown
47+ * the interrupt status of the previously-blocked thread will have been set." \
48+ 7104080643653532383L
49+
50+
51+SUPER=ClosedChannelException
52+
53+gen AsynchronousCloseException "
54+ * Checked exception received by a thread when another thread closes the
55+ * channel or the part of the channel upon which it is blocked in an I/O
56+ * operation." \
57+ 6891178312432313966L
58+
59+
60+SUPER=AsynchronousCloseException
61+
62+gen ClosedByInterruptException "
63+ * Checked exception received by a thread when another thread interrupts it
64+ * while it is blocked in an I/O operation upon a channel. Before this
65+ * exception is thrown the channel will have been closed and the interrupt
66+ * status of the previously-blocked thread will have been set." \
67+ -4488191543534286750L
68+
69+
70+SUPER=IllegalArgumentException
71+
72+gen IllegalSelectorException "
73+ * Unchecked exception thrown when an attempt is made to register a channel
74+ * with a selector that was not created by the provider that created the
75+ * channel." \
76+ -8406323347253320987L
77+
78+gen UnresolvedAddressException "
79+ * Unchecked exception thrown when an attempt is made to invoke a network
80+ * operation upon an unresolved socket address." \
81+ 6136959093620794148L
82+
83+gen UnsupportedAddressTypeException "
84+ * Unchecked exception thrown when an attempt is made to bind or connect
85+ * to a socket address of a type that is not supported." \
86+ -2964323842829700493L
87+
88+
89+SUPER=IllegalStateException
90+
91+gen AlreadyConnectedException "
92+ * Unchecked exception thrown when an attempt is made to connect a {@link
93+ * SocketChannel} that is already connected." \
94+ -7331895245053773357L
95+
96+gen ConnectionPendingException "
97+ * Unchecked exception thrown when an attempt is made to connect a {@link
98+ * SocketChannel} for which a non-blocking connection operation is already in
99+ * progress." \
100+ 2008393366501760879L
101+
102+gen ClosedSelectorException "
103+ * Unchecked exception thrown when an attempt is made to invoke an I/O
104+ * operation upon a closed selector." \
105+ 6466297122317847835L
106+
107+gen CancelledKeyException "
108+ * Unchecked exception thrown when an attempt is made to use
109+ * a selection key that is no longer valid." \
110+ -8438032138028814268L
111+
112+gen IllegalBlockingModeException "
113+ * Unchecked exception thrown when a blocking-mode-specific operation
114+ * is invoked upon a channel in the incorrect blocking mode." \
115+ -3335774961855590474L
116+
117+gen NoConnectionPendingException "
118+ * Unchecked exception thrown when the {@link SocketChannel#finishConnect
119+ * finishConnect} method of a {@link SocketChannel} is invoked without first
120+ * successfully invoking its {@link SocketChannel#connect connect} method." \
121+ -8296561183633134743L
122+
123+gen NonReadableChannelException "
124+ * Unchecked exception thrown when an attempt is made to read
125+ * from a channel that was not originally opened for reading." \
126+ -3200915679294993514L
127+
128+gen NonWritableChannelException "
129+ * Unchecked exception thrown when an attempt is made to write
130+ * to a channel that was not originally opened for writing." \
131+ -7071230488279011621L
132+
133+gen NotYetBoundException "
134+ * Unchecked exception thrown when an attempt is made to invoke an I/O
135+ * operation upon a server socket channel that is not yet bound." \
136+ 4640999303950202242L
137+
138+gen NotYetConnectedException "
139+ * Unchecked exception thrown when an attempt is made to invoke an I/O
140+ * operation upon a socket channel that is not yet connected." \
141+ 4697316551909513464L
142+
143+gen OverlappingFileLockException "
144+ * Unchecked exception thrown when an attempt is made to acquire a lock on a
145+ * region of a file that overlaps a region already locked by the same Java
146+ * virtual machine, or when another thread is already waiting to lock an
147+ * overlapping region of the same file." \
148+ 2047812138163068433L
149+
150+
151+SINCE=1.7
152+
153+SUPER=java.io.IOException
154+
155+gen InterruptedByTimeoutException "
156+ * Checked exception received by a thread when a timeout elapses before an
157+ * asynchronous operation completes." \
158+ -4268008601014042947L
159+
160+SUPER=IllegalArgumentException
161+
162+gen IllegalChannelGroupException "
163+ * Unchecked exception thrown when an attempt is made to open a channel
164+ * in a group that was not created by the same provider. " \
165+ -2495041211157744253L
166+
167+
168+SUPER=IllegalStateException
169+
170+gen AlreadyBoundException "
171+ * Unchecked exception thrown when an attempt is made to bind the socket a
172+ * network oriented channel that is already bound." \
173+ 6796072983322737592L
174+
175+gen AcceptPendingException "
176+ * Unchecked exception thrown when an attempt is made to initiate an accept
177+ * operation on a channel and a previous accept operation has not completed." \
178+ 2721339977965416421L
179+
180+gen ReadPendingException "
181+ * Unchecked exception thrown when an attempt is made to read from an
182+ * asynchronous socket channel and a previous read has not completed." \
183+ 1986315242191227217L
184+
185+gen WritePendingException "
186+ * Unchecked exception thrown when an attempt is made to write to an
187+ * asynchronous socket channel and a previous write has not completed." \
188+ 7031871839266032276L
189+
190+gen ShutdownChannelGroupException "
191+ * Unchecked exception thrown when an attempt is made to construct a channel in
192+ * a group that is shutdown or the completion handler for an I/O operation
193+ * cannot be invoked because the channel group has terminated." \
194+ -3903801676350154157L
java/pkg/java/nio/channels/mkfile+40−0
@@ -0,0 +1,40 @@
1+<../../../../../mkconfig
2+
3+DIRS=\
4+ spi\
5+
6+TARG=\
7+ AsynchronousByteChannel.dis\
8+ AsynchronousChannel.dis\
9+ AsynchronousChannelGroup.dis\
10+ AsynchronousFileChannel.dis\
11+ AsynchronousServerSocketChannel.dis\
12+ AsynchronousSocketChannel.dis\
13+ ByteChannel.dis\
14+ Channel.dis\
15+ Channels.dis\
16+ CompletionHandler.dis\
17+ DatagramChannel.dis\
18+ FileChannel.dis\
19+ FileLock.dis\
20+ GatheringByteChannel.dis\
21+ InterruptibleChannel.dis\
22+ MembershipKey.dis\
23+ MulticastChannel.dis\
24+ NetworkChannel.dis\
25+ package-info.dis\
26+ Pipe.dis\
27+ ReadableByteChannel.dis\
28+ ScatteringByteChannel.dis\
29+ SeekableByteChannel.dis\
30+ SelectableChannel.dis\
31+ SelectionKey.dis\
32+ Selector.dis\
33+ ServerSocketChannel.dis\
34+ SocketChannel.dis\
35+ WritableByteChannel.dis\
36+
37+DISBIN=$ROOT/java/dis/java/java/java/nio/channels
38+
39+<$ROOT/mkfiles/mkjava
40+<$ROOT/mkfiles/mksubdirs
java/pkg/java/nio/channels/package-info.java+290−0
@@ -0,0 +1,290 @@
1+/*
2+ * Copyright (c) 2001, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+/**
27+ * Defines channels, which represent connections to entities that are capable of
28+ * performing I/O operations, such as files and sockets; defines selectors, for
29+ * multiplexed, non-blocking I/O operations.
30+ *
31+ * <a name="channels"></a>
32+ *
33+ * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions">
34+ * <tr><th><p align="left">Channels</p></th><th><p align="left">Description</p></th></tr>
35+ * <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td>
36+ * <td>A nexus for I/O operations</td></tr>
37+ * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>
38+ * <td>Can read into a buffer</td></tr>
39+ * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.ScatteringByteChannel}&nbsp;&nbsp;</i></tt></td>
40+ * <td>Can read into a sequence of&nbsp;buffers</td></tr>
41+ * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.WritableByteChannel}</i></tt></td>
42+ * <td>Can write from a buffer</td></tr>
43+ * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td>
44+ * <td>Can write from a sequence of&nbsp;buffers</td></tr>
45+ * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ByteChannel}</i></tt></td>
46+ * <td>Can read/write to/from a&nbsp;buffer</td></tr>
47+ * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.SeekableByteChannel}</i></tt></td>
48+ * <td>A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes</td></tr>
49+ * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousChannel}</i></tt></td>
50+ * <td>Supports asynchronous I/O operations.</td></tr>
51+ * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousByteChannel}</i></tt></td>
52+ * <td>Can read and write bytes asynchronously</td></tr>
53+ * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.NetworkChannel}</i></tt></td>
54+ * <td>A channel to a network socket</td></tr>
55+ * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.MulticastChannel}</i></tt></td>
56+ * <td>Can join Internet Protocol (IP) multicast groups</td></tr>
57+ * <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td>
58+ * <td>Utility methods for channel/stream interoperation</td></tr>
59+ * </table></blockquote>
60+ *
61+ * <p> A <i>channel</i> represents an open connection to an entity such as a
62+ * hardware device, a file, a network socket, or a program component that is
63+ * capable of performing one or more distinct I/O operations, for example reading
64+ * or writing. As specified in the {@link java.nio.channels.Channel} interface,
65+ * channels are either open or closed, and they are both <i>asynchronously
66+ * closeable</i> and <i>interruptible</i>.
67+ *
68+ * <p> The {@link java.nio.channels.Channel} interface is extended by several
69+ * other interfaces.
70+ *
71+ * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a
72+ * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes
73+ * from the channel into a buffer; similarly, the {@link
74+ * java.nio.channels.WritableByteChannel} interface specifies a {@link
75+ * java.nio.channels.WritableByteChannel#write write} method that writes bytes
76+ * from a buffer to the channel. The {@link java.nio.channels.ByteChannel}
77+ * interface unifies these two interfaces for the common case of channels that can
78+ * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel}
79+ * interface extends the {@code ByteChannel} interface with methods to {@link
80+ * java.nio.channels.SeekableByteChannel#position() query} and {@link
81+ * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's
82+ * current position, and its {@link java.nio.channels.SeekableByteChannel#size
83+ * size}.
84+ *
85+ * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
86+ * java.nio.channels.GatheringByteChannel} interfaces extend the {@link
87+ * java.nio.channels.ReadableByteChannel} and {@link
88+ * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
89+ * java.nio.channels.ScatteringByteChannel#read read} and {@link
90+ * java.nio.channels.GatheringByteChannel#write write} methods that take a
91+ * sequence of buffers rather than a single buffer.
92+ *
93+ * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods
94+ * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,
95+ * obtain the address to which the socket is bound, and methods to {@link
96+ * java.nio.channels.NetworkChannel#getOption get} and {@link
97+ * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link
98+ * java.nio.channels.MulticastChannel} interface specifies methods to join
99+ * Internet Protocol (IP) multicast groups.
100+ *
101+ * <p> The {@link java.nio.channels.Channels} utility class defines static methods
102+ * that support the interoperation of the stream classes of the <tt>{@link
103+ * java.io}</tt> package with the channel classes of this package. An appropriate
104+ * channel can be constructed from an {@link java.io.InputStream} or an {@link
105+ * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an
106+ * {@link java.io.OutputStream} can be constructed from a channel. A {@link
107+ * java.io.Reader} can be constructed that uses a given charset to decode bytes
108+ * from a given readable byte channel, and conversely a {@link java.io.Writer} can
109+ * be constructed that uses a given charset to encode characters into bytes and
110+ * write them to a given writable byte channel.
111+ *
112+ * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">
113+ * <tr><th><p align="left">File channels</p></th><th><p align="left">Description</p></th></tr>
114+ * <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>
115+ * <td>Reads, writes, maps, and manipulates files</td></tr>
116+ * <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>
117+ * <td>A lock on a (region of a) file</td></tr>
118+ * <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer}&nbsp;&nbsp;</tt></td>
119+ * <td>A direct byte buffer mapped to a region of a&nbsp;file</td></tr>
120+ * </table></blockquote>
121+ *
122+ * <p> The {@link java.nio.channels.FileChannel} class supports the usual
123+ * operations of reading bytes from, and writing bytes to, a channel connected to
124+ * a file, as well as those of querying and modifying the current file position
125+ * and truncating the file to a specific size. It defines methods for acquiring
126+ * locks on the whole file or on a specific region of a file; these methods return
127+ * instances of the {@link java.nio.channels.FileLock} class. Finally, it defines
128+ * methods for forcing updates to the file to be written to the storage device that
129+ * contains it, for efficiently transferring bytes between the file and other
130+ * channels, and for mapping a region of the file directly into memory.
131+ *
132+ * <p> A {@code FileChannel} is created by invoking one of its static {@link
133+ * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code
134+ * getChannel} method of a {@link java.io.FileInputStream}, {@link
135+ * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a
136+ * file channel connected to the same underlying file as the <tt>{@link java.io}</tt>
137+ * class.
138+ *
139+ * <a name="multiplex"></a>
140+ * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">
141+ * <tr><th><p align="left">Multiplexed, non-blocking I/O</p></th><th><p align="left">Description</p></th></tr>
142+ * <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>
143+ * <td>A channel that can be multiplexed</td></tr>
144+ * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.DatagramChannel}</tt></td>
145+ * <td>A channel to a datagram-oriented socket</td></tr>
146+ * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SinkChannel}</tt></td>
147+ * <td>The write end of a pipe</td></tr>
148+ * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SourceChannel}</tt></td>
149+ * <td>The read end of a pipe</td></tr>
150+ * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.ServerSocketChannel}&nbsp;&nbsp;</tt></td>
151+ * <td>A channel to a stream-oriented listening socket</td></tr>
152+ * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.SocketChannel}</tt></td>
153+ * <td>A channel for a stream-oriented connecting socket</td></tr>
154+ * <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td>
155+ * <td>A multiplexor of selectable channels</td></tr>
156+ * <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td>
157+ * <td>A token representing the registration <br> of a channel
158+ * with&nbsp;a&nbsp;selector</td></tr>
159+ * <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>
160+ * <td>Two channels that form a unidirectional&nbsp;pipe</td></tr>
161+ * </table></blockquote>
162+ *
163+ * <p> Multiplexed, non-blocking I/O, which is much more scalable than
164+ * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable
165+ * channels</i>, and <i>selection keys</i>.
166+ *
167+ * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a
168+ * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are
169+ * a special type of channel that can be put into <a
170+ * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>. To perform
171+ * multiplexed I/O operations, one or more selectable channels are first created,
172+ * put into non-blocking mode, and {@link
173+ * java.nio.channels.SelectableChannel#register <i>registered</i>}
174+ * with a selector. Registering a channel specifies the set of I/O operations
175+ * that will be tested for readiness by the selector, and returns a <a
176+ * href="SelectionKey.html"><i>selection key</i></a> that represents the
177+ * registration.
178+ *
179+ * <p> Once some channels have been registered with a selector, a <a
180+ * href="Selector.html#selop"><i>selection operation</i></a> can be performed in
181+ * order to discover which channels, if any, have become ready to perform one or
182+ * more of the operations in which interest was previously declared. If a channel
183+ * is ready then the key returned when it was registered will be added to the
184+ * selector's <i>selected-key set</i>. The key set, and the keys within it, can
185+ * be examined in order to determine the operations for which each channel is
186+ * ready. From each key one can retrieve the corresponding channel in order to
187+ * perform whatever I/O operations are required.
188+ *
189+ * <p> That a selection key indicates that its channel is ready for some operation
190+ * is a hint, but not a guarantee, that such an operation can be performed by a
191+ * thread without causing the thread to block. It is imperative that code that
192+ * performs multiplexed I/O be written so as to ignore these hints when they prove
193+ * to be incorrect.
194+ *
195+ * <p> This package defines selectable-channel classes corresponding to the {@link
196+ * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link
197+ * java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package.
198+ * Minor changes to these classes have been made in order to support sockets that
199+ * are associated with channels. This package also defines a simple class that
200+ * implements unidirectional pipes. In all cases, a new selectable channel is
201+ * created by invoking the static <tt>open</tt> method of the corresponding class.
202+ * If a channel needs an associated socket then a socket will be created as a side
203+ * effect of this operation.
204+ *
205+ * <p> The implementation of selectors, selectable channels, and selection keys
206+ * can be replaced by "plugging in" an alternative definition or instance of the
207+ * {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link
208+ * java.nio.channels.spi}</tt> package. It is not expected that many developers
209+ * will actually make use of this facility; it is provided primarily so that
210+ * sophisticated users can take advantage of operating-system-specific
211+ * I/O-multiplexing mechanisms when very high performance is required.
212+ *
213+ * <p> Much of the bookkeeping and synchronization required to implement the
214+ * multiplexed-I/O abstractions is performed by the {@link
215+ * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link
216+ * java.nio.channels.spi.AbstractSelectableChannel}, {@link
217+ * java.nio.channels.spi.AbstractSelectionKey}, and {@link
218+ * java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link
219+ * java.nio.channels.spi}</tt> package. When defining a custom selector provider,
220+ * only the {@link java.nio.channels.spi.AbstractSelector} and {@link
221+ * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed
222+ * directly; custom channel classes should extend the appropriate {@link
223+ * java.nio.channels.SelectableChannel} subclasses defined in this package.
224+ *
225+ * <a name="async"></a>
226+ *
227+ * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists asynchronous channels and their descriptions">
228+ * <tr><th><p align="left">Asynchronous I/O</p></th><th><p align="left">Description</p></th></tr>
229+ * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousFileChannel}</tt></td>
230+ * <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr>
231+ * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousSocketChannel}</tt></td>
232+ * <td>An asynchronous channel to a stream-oriented connecting socket</td></tr>
233+ * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousServerSocketChannel}&nbsp;&nbsp;</tt></td>
234+ * <td>An asynchronous channel to a stream-oriented listening socket</td></tr>
235+ * <tr><td valign=top><tt>{@link java.nio.channels.CompletionHandler}</tt></td>
236+ * <td>A handler for consuming the result of an asynchronous operation</td></tr>
237+ * <tr><td valign=top><tt>{@link java.nio.channels.AsynchronousChannelGroup}</tt></td>
238+ * <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr>
239+ * </table></blockquote>
240+ *
241+ * <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a
242+ * special type of channel capable of asynchronous I/O operations. Asynchronous
243+ * channels are non-blocking and define methods to initiate asynchronous
244+ * operations, returning a {@link java.util.concurrent.Future} representing the
245+ * pending result of each operation. The {@code Future} can be used to poll or
246+ * wait for the result of the operation. Asynchronous I/O operations can also
247+ * specify a {@link java.nio.channels.CompletionHandler} to invoke when the
248+ * operation completes. A completion handler is user provided code that is executed
249+ * to consume the result of I/O operation.
250+ *
251+ * <p> This package defines asynchronous-channel classes that are connected to
252+ * a stream-oriented connecting or listening socket, or a datagram-oriented socket.
253+ * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class
254+ * for asynchronous reading, writing, and manipulating a file. As with the {@link
255+ * java.nio.channels.FileChannel} it supports operations to truncate the file
256+ * to a specific size, force updates to the file to be written to the storage
257+ * device, or acquire locks on the whole file or on a specific region of the file.
258+ * Unlike the {@code FileChannel} it does not define methods for mapping a
259+ * region of the file directly into memory. Where memory mapped I/O is required,
260+ * then a {@code FileChannel} can be used.
261+ *
262+ * <p> Asynchronous channels are bound to an asynchronous channel group for the
263+ * purpose of resource sharing. A group has an associated {@link
264+ * java.util.concurrent.ExecutorService} to which tasks are submitted to handle
265+ * I/O events and dispatch to completion handlers that consume the result of
266+ * asynchronous operations performed on channels in the group. The group can
267+ * optionally be specified when creating the channel or the channel can be bound
268+ * to a <em>default group</em>. Sophisticated users may wish to create their
269+ * own asynchronous channel groups or configure the {@code ExecutorService}
270+ * that will be used for the default group.
271+ *
272+ * <p> As with selectors, the implementatin of asynchronous channels can be
273+ * replaced by "plugging in" an alternative definition or instance of the {@link
274+ * java.nio.channels.spi.AsynchronousChannelProvider} class defined in the
275+ * <tt>{@link java.nio.channels.spi}</tt> package. It is not expected that many
276+ * developers will actually make use of this facility; it is provided primarily
277+ * so that sophisticated users can take advantage of operating-system-specific
278+ * asynchronous I/O mechanisms when very high performance is required.
279+ *
280+ * <hr width="80%">
281+ * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
282+ * or method in any class or interface in this package will cause a {@link
283+ * java.lang.NullPointerException NullPointerException} to be thrown.
284+ *
285+ * @since 1.4
286+ * @author Mark Reinhold
287+ * @author JSR-51 Expert Group
288+ */
289+
290+package java.nio.channels;
java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel$1.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractInterruptibleChannel.java+214−0
@@ -0,0 +1,214 @@
1+/*
2+ * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+/*
27+ */
28+
29+package java.nio.channels.spi;
30+
31+import java.io.IOException;
32+import java.lang.reflect.Method;
33+import java.lang.reflect.InvocationTargetException;
34+import java.nio.channels.*;
35+import java.security.AccessController;
36+import java.security.PrivilegedAction;
37+import sun.nio.ch.Interruptible;
38+
39+
40+/**
41+ * Base implementation class for interruptible channels.
42+ *
43+ * <p> This class encapsulates the low-level machinery required to implement
44+ * the asynchronous closing and interruption of channels. A concrete channel
45+ * class must invoke the {@link #begin begin} and {@link #end end} methods
46+ * before and after, respectively, invoking an I/O operation that might block
47+ * indefinitely. In order to ensure that the {@link #end end} method is always
48+ * invoked, these methods should be used within a
49+ * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block: <a name="be">
50+ *
51+ * <blockquote><pre>
52+ * boolean completed = false;
53+ * try {
54+ * begin();
55+ * completed = ...; // Perform blocking I/O operation
56+ * return ...; // Return result
57+ * } finally {
58+ * end(completed);
59+ * }</pre></blockquote>
60+ *
61+ * <p> The <tt>completed</tt> argument to the {@link #end end} method tells
62+ * whether or not the I/O operation actually completed, that is, whether it had
63+ * any effect that would be visible to the invoker. In the case of an
64+ * operation that reads bytes, for example, this argument should be
65+ * <tt>true</tt> if, and only if, some bytes were actually transferred into the
66+ * invoker's target buffer.
67+ *
68+ * <p> A concrete channel class must also implement the {@link
69+ * #implCloseChannel implCloseChannel} method in such a way that if it is
70+ * invoked while another thread is blocked in a native I/O operation upon the
71+ * channel then that operation will immediately return, either by throwing an
72+ * exception or by returning normally. If a thread is interrupted or the
73+ * channel upon which it is blocked is asynchronously closed then the channel's
74+ * {@link #end end} method will throw the appropriate exception.
75+ *
76+ * <p> This class performs the synchronization required to implement the {@link
77+ * java.nio.channels.Channel} specification. Implementations of the {@link
78+ * #implCloseChannel implCloseChannel} method need not synchronize against
79+ * other threads that might be attempting to close the channel. </p>
80+ *
81+ *
82+ * @author Mark Reinhold
83+ * @author JSR-51 Expert Group
84+ * @since 1.4
85+ */
86+
87+public abstract class AbstractInterruptibleChannel
88+ implements Channel, InterruptibleChannel
89+{
90+
91+ private final Object closeLock = new Object();
92+ private volatile boolean open = true;
93+
94+ /**
95+ * Initializes a new instance of this class.
96+ */
97+ protected AbstractInterruptibleChannel() { }
98+
99+ /**
100+ * Closes this channel.
101+ *
102+ * <p> If the channel has already been closed then this method returns
103+ * immediately. Otherwise it marks the channel as closed and then invokes
104+ * the {@link #implCloseChannel implCloseChannel} method in order to
105+ * complete the close operation. </p>
106+ *
107+ * @throws IOException
108+ * If an I/O error occurs
109+ */
110+ public final void close() throws IOException {
111+ synchronized (closeLock) {
112+ if (!open)
113+ return;
114+ open = false;
115+ implCloseChannel();
116+ }
117+ }
118+
119+ /**
120+ * Closes this channel.
121+ *
122+ * <p> This method is invoked by the {@link #close close} method in order
123+ * to perform the actual work of closing the channel. This method is only
124+ * invoked if the channel has not yet been closed, and it is never invoked
125+ * more than once.
126+ *
127+ * <p> An implementation of this method must arrange for any other thread
128+ * that is blocked in an I/O operation upon this channel to return
129+ * immediately, either by throwing an exception or by returning normally.
130+ * </p>
131+ *
132+ * @throws IOException
133+ * If an I/O error occurs while closing the channel
134+ */
135+ protected abstract void implCloseChannel() throws IOException;
136+
137+ public final boolean isOpen() {
138+ return open;
139+ }
140+
141+
142+ // -- Interruption machinery --
143+
144+ private Interruptible interruptor;
145+ private volatile Thread interrupted;
146+
147+ /**
148+ * Marks the beginning of an I/O operation that might block indefinitely.
149+ *
150+ * <p> This method should be invoked in tandem with the {@link #end end}
151+ * method, using a <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block as
152+ * shown <a href="#be">above</a>, in order to implement asynchronous
153+ * closing and interruption for this channel. </p>
154+ */
155+ protected final void begin() {
156+ if (interruptor == null) {
157+ interruptor = new Interruptible() {
158+ public void interrupt(Thread target) {
159+ synchronized (closeLock) {
160+ if (!open)
161+ return;
162+ open = false;
163+ interrupted = target;
164+ try {
165+ AbstractInterruptibleChannel.this.implCloseChannel();
166+ } catch (IOException x) { }
167+ }
168+ }};
169+ }
170+ blockedOn(interruptor);
171+ Thread me = Thread.currentThread();
172+ if (me.isInterrupted())
173+ interruptor.interrupt(me);
174+ }
175+
176+ /**
177+ * Marks the end of an I/O operation that might block indefinitely.
178+ *
179+ * <p> This method should be invoked in tandem with the {@link #begin
180+ * begin} method, using a <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block
181+ * as shown <a href="#be">above</a>, in order to implement asynchronous
182+ * closing and interruption for this channel. </p>
183+ *
184+ * @param completed
185+ * <tt>true</tt> if, and only if, the I/O operation completed
186+ * successfully, that is, had some effect that would be visible to
187+ * the operation's invoker
188+ *
189+ * @throws AsynchronousCloseException
190+ * If the channel was asynchronously closed
191+ *
192+ * @throws ClosedByInterruptException
193+ * If the thread blocked in the I/O operation was interrupted
194+ */
195+ protected final void end(boolean completed)
196+ throws AsynchronousCloseException
197+ {
198+ blockedOn(null);
199+ Thread interrupted = this.interrupted;
200+ if (interrupted != null && interrupted == Thread.currentThread()) {
201+ interrupted = null;
202+ throw new ClosedByInterruptException();
203+ }
204+ if (!completed && !open)
205+ throw new AsynchronousCloseException();
206+ }
207+
208+
209+ // -- sun.misc.SharedSecrets --
210+ static void blockedOn(Interruptible intr) { // package-private
211+ sun.misc.SharedSecrets.getJavaLangAccess().blockedOn(Thread.currentThread(),
212+ intr);
213+ }
214+}
java/pkg/java/nio/channels/spi/AbstractSelectableChannel.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractSelectableChannel.java+305−0
@@ -0,0 +1,305 @@
1+/*
2+ * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels.spi;
27+
28+import java.io.IOException;
29+import java.nio.channels.*;
30+
31+
32+/**
33+ * Base implementation class for selectable channels.
34+ *
35+ * <p> This class defines methods that handle the mechanics of channel
36+ * registration, deregistration, and closing. It maintains the current
37+ * blocking mode of this channel as well as its current set of selection keys.
38+ * It performs all of the synchronization required to implement the {@link
39+ * java.nio.channels.SelectableChannel} specification. Implementations of the
40+ * abstract protected methods defined in this class need not synchronize
41+ * against other threads that might be engaged in the same operations. </p>
42+ *
43+ *
44+ * @author Mark Reinhold
45+ * @author Mike McCloskey
46+ * @author JSR-51 Expert Group
47+ * @since 1.4
48+ */
49+
50+public abstract class AbstractSelectableChannel
51+ extends SelectableChannel
52+{
53+
54+ // The provider that created this channel
55+ private final SelectorProvider provider;
56+
57+ // Keys that have been created by registering this channel with selectors.
58+ // They are saved because if this channel is closed the keys must be
59+ // deregistered. Protected by keyLock.
60+ //
61+ private SelectionKey[] keys = null;
62+ private int keyCount = 0;
63+
64+ // Lock for key set and count
65+ private final Object keyLock = new Object();
66+
67+ // Lock for registration and configureBlocking operations
68+ private final Object regLock = new Object();
69+
70+ // Blocking mode, protected by regLock
71+ boolean blocking = true;
72+
73+ /**
74+ * Initializes a new instance of this class.
75+ */
76+ protected AbstractSelectableChannel(SelectorProvider provider) {
77+ this.provider = provider;
78+ }
79+
80+ /**
81+ * Returns the provider that created this channel.
82+ *
83+ * @return The provider that created this channel
84+ */
85+ public final SelectorProvider provider() {
86+ return provider;
87+ }
88+
89+
90+ // -- Utility methods for the key set --
91+
92+ private void addKey(SelectionKey k) {
93+ synchronized (keyLock) {
94+ int i = 0;
95+ if ((keys != null) && (keyCount < keys.length)) {
96+ // Find empty element of key array
97+ for (i = 0; i < keys.length; i++)
98+ if (keys[i] == null)
99+ break;
100+ } else if (keys == null) {
101+ keys = new SelectionKey[3];
102+ } else {
103+ // Grow key array
104+ int n = keys.length * 2;
105+ SelectionKey[] ks = new SelectionKey[n];
106+ for (i = 0; i < keys.length; i++)
107+ ks[i] = keys[i];
108+ keys = ks;
109+ i = keyCount;
110+ }
111+ keys[i] = k;
112+ keyCount++;
113+ }
114+ }
115+
116+ private SelectionKey findKey(Selector sel) {
117+ synchronized (keyLock) {
118+ if (keys == null)
119+ return null;
120+ for (int i = 0; i < keys.length; i++)
121+ if ((keys[i] != null) && (keys[i].selector() == sel))
122+ return keys[i];
123+ return null;
124+ }
125+ }
126+
127+ void removeKey(SelectionKey k) { // package-private
128+ synchronized (keyLock) {
129+ for (int i = 0; i < keys.length; i++)
130+ if (keys[i] == k) {
131+ keys[i] = null;
132+ keyCount--;
133+ }
134+ ((AbstractSelectionKey)k).invalidate();
135+ }
136+ }
137+
138+ private boolean haveValidKeys() {
139+ synchronized (keyLock) {
140+ if (keyCount == 0)
141+ return false;
142+ for (int i = 0; i < keys.length; i++) {
143+ if ((keys[i] != null) && keys[i].isValid())
144+ return true;
145+ }
146+ return false;
147+ }
148+ }
149+
150+
151+ // -- Registration --
152+
153+ public final boolean isRegistered() {
154+ synchronized (keyLock) {
155+ return keyCount != 0;
156+ }
157+ }
158+
159+ public final SelectionKey keyFor(Selector sel) {
160+ return findKey(sel);
161+ }
162+
163+ /**
164+ * Registers this channel with the given selector, returning a selection key.
165+ *
166+ * <p> This method first verifies that this channel is open and that the
167+ * given initial interest set is valid.
168+ *
169+ * <p> If this channel is already registered with the given selector then
170+ * the selection key representing that registration is returned after
171+ * setting its interest set to the given value.
172+ *
173+ * <p> Otherwise this channel has not yet been registered with the given
174+ * selector, so the {@link AbstractSelector#register register} method of
175+ * the selector is invoked while holding the appropriate locks. The
176+ * resulting key is added to this channel's key set before being returned.
177+ * </p>
178+ *
179+ * @throws ClosedSelectorException {@inheritDoc}
180+ *
181+ * @throws IllegalBlockingModeException {@inheritDoc}
182+ *
183+ * @throws IllegalSelectorException {@inheritDoc}
184+ *
185+ * @throws CancelledKeyException {@inheritDoc}
186+ *
187+ * @throws IllegalArgumentException {@inheritDoc}
188+ */
189+ public final SelectionKey register(Selector sel, int ops,
190+ Object att)
191+ throws ClosedChannelException
192+ {
193+ if (!isOpen())
194+ throw new ClosedChannelException();
195+ if ((ops & ~validOps()) != 0)
196+ throw new IllegalArgumentException();
197+ synchronized (regLock) {
198+ if (blocking)
199+ throw new IllegalBlockingModeException();
200+ SelectionKey k = findKey(sel);
201+ if (k != null) {
202+ k.interestOps(ops);
203+ k.attach(att);
204+ }
205+ if (k == null) {
206+ // New registration
207+ k = ((AbstractSelector)sel).register(this, ops, att);
208+ addKey(k);
209+ }
210+ return k;
211+ }
212+ }
213+
214+
215+ // -- Closing --
216+
217+ /**
218+ * Closes this channel.
219+ *
220+ * <p> This method, which is specified in the {@link
221+ * AbstractInterruptibleChannel} class and is invoked by the {@link
222+ * java.nio.channels.Channel#close close} method, in turn invokes the
223+ * {@link #implCloseSelectableChannel implCloseSelectableChannel} method in
224+ * order to perform the actual work of closing this channel. It then
225+ * cancels all of this channel's keys. </p>
226+ */
227+ protected final void implCloseChannel() throws IOException {
228+ implCloseSelectableChannel();
229+ synchronized (keyLock) {
230+ int count = (keys == null) ? 0 : keys.length;
231+ for (int i = 0; i < count; i++) {
232+ SelectionKey k = keys[i];
233+ if (k != null)
234+ k.cancel();
235+ }
236+ }
237+ }
238+
239+ /**
240+ * Closes this selectable channel.
241+ *
242+ * <p> This method is invoked by the {@link java.nio.channels.Channel#close
243+ * close} method in order to perform the actual work of closing the
244+ * channel. This method is only invoked if the channel has not yet been
245+ * closed, and it is never invoked more than once.
246+ *
247+ * <p> An implementation of this method must arrange for any other thread
248+ * that is blocked in an I/O operation upon this channel to return
249+ * immediately, either by throwing an exception or by returning normally.
250+ * </p>
251+ */
252+ protected abstract void implCloseSelectableChannel() throws IOException;
253+
254+
255+ // -- Blocking --
256+
257+ public final boolean isBlocking() {
258+ synchronized (regLock) {
259+ return blocking;
260+ }
261+ }
262+
263+ public final Object blockingLock() {
264+ return regLock;
265+ }
266+
267+ /**
268+ * Adjusts this channel's blocking mode.
269+ *
270+ * <p> If the given blocking mode is different from the current blocking
271+ * mode then this method invokes the {@link #implConfigureBlocking
272+ * implConfigureBlocking} method, while holding the appropriate locks, in
273+ * order to change the mode. </p>
274+ */
275+ public final SelectableChannel configureBlocking(boolean block)
276+ throws IOException
277+ {
278+ if (!isOpen())
279+ throw new ClosedChannelException();
280+ synchronized (regLock) {
281+ if (blocking == block)
282+ return this;
283+ if (block && haveValidKeys())
284+ throw new IllegalBlockingModeException();
285+ implConfigureBlocking(block);
286+ blocking = block;
287+ }
288+ return this;
289+ }
290+
291+ /**
292+ * Adjusts this channel's blocking mode.
293+ *
294+ * <p> This method is invoked by the {@link #configureBlocking
295+ * configureBlocking} method in order to perform the actual work of
296+ * changing the blocking mode. This method is only invoked if the new mode
297+ * is different from the current mode. </p>
298+ *
299+ * @throws IOException
300+ * If an I/O error occurs
301+ */
302+ protected abstract void implConfigureBlocking(boolean block)
303+ throws IOException;
304+
305+}
java/pkg/java/nio/channels/spi/AbstractSelectionKey.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractSelectionKey.java+77−0
@@ -0,0 +1,77 @@
1+/*
2+ * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels.spi;
27+
28+import java.nio.channels.*;
29+
30+
31+/**
32+ * Base implementation class for selection keys.
33+ *
34+ * <p> This class tracks the validity of the key and implements cancellation.
35+ *
36+ * @author Mark Reinhold
37+ * @author JSR-51 Expert Group
38+ * @since 1.4
39+ */
40+
41+public abstract class AbstractSelectionKey
42+ extends SelectionKey
43+{
44+
45+ /**
46+ * Initializes a new instance of this class. </p>
47+ */
48+ protected AbstractSelectionKey() { }
49+
50+ private volatile boolean valid = true;
51+
52+ public final boolean isValid() {
53+ return valid;
54+ }
55+
56+ void invalidate() { // package-private
57+ valid = false;
58+ }
59+
60+ /**
61+ * Cancels this key.
62+ *
63+ * <p> If this key has not yet been cancelled then it is added to its
64+ * selector's cancelled-key set while synchronized on that set. </p>
65+ */
66+ public final void cancel() {
67+ // Synchronizing "this" to prevent this key from getting canceled
68+ // multiple times by different threads, which might cause race
69+ // condition between selector's select() and channel's close().
70+ synchronized (this) {
71+ if (valid) {
72+ valid = false;
73+ ((AbstractSelector)selector()).cancel(this);
74+ }
75+ }
76+ }
77+}
java/pkg/java/nio/channels/spi/AbstractSelector$1.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractSelector.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AbstractSelector.java+231−0
@@ -0,0 +1,231 @@
1+/*
2+ * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels.spi;
27+
28+import java.io.IOException;
29+import java.nio.channels.SelectionKey;
30+import java.nio.channels.Selector;
31+import java.util.HashSet;
32+import java.util.Set;
33+import sun.nio.ch.Interruptible;
34+import java.util.concurrent.atomic.AtomicBoolean;
35+
36+
37+/**
38+ * Base implementation class for selectors.
39+ *
40+ * <p> This class encapsulates the low-level machinery required to implement
41+ * the interruption of selection operations. A concrete selector class must
42+ * invoke the {@link #begin begin} and {@link #end end} methods before and
43+ * after, respectively, invoking an I/O operation that might block
44+ * indefinitely. In order to ensure that the {@link #end end} method is always
45+ * invoked, these methods should be used within a
46+ * <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block: <a name="be">
47+ *
48+ * <blockquote><pre>
49+ * try {
50+ * begin();
51+ * // Perform blocking I/O operation here
52+ * ...
53+ * } finally {
54+ * end();
55+ * }</pre></blockquote>
56+ *
57+ * <p> This class also defines methods for maintaining a selector's
58+ * cancelled-key set and for removing a key from its channel's key set, and
59+ * declares the abstract {@link #register register} method that is invoked by a
60+ * selectable channel's {@link AbstractSelectableChannel#register register}
61+ * method in order to perform the actual work of registering a channel. </p>
62+ *
63+ *
64+ * @author Mark Reinhold
65+ * @author JSR-51 Expert Group
66+ * @since 1.4
67+ */
68+
69+public abstract class AbstractSelector
70+ extends Selector
71+{
72+
73+ private AtomicBoolean selectorOpen = new AtomicBoolean(true);
74+
75+ // The provider that created this selector
76+ private final SelectorProvider provider;
77+
78+ /**
79+ * Initializes a new instance of this class. </p>
80+ */
81+ protected AbstractSelector(SelectorProvider provider) {
82+ this.provider = provider;
83+ }
84+
85+ private final Set<SelectionKey> cancelledKeys = new HashSet<SelectionKey>();
86+
87+ void cancel(SelectionKey k) { // package-private
88+ synchronized (cancelledKeys) {
89+ cancelledKeys.add(k);
90+ }
91+ }
92+
93+ /**
94+ * Closes this selector.
95+ *
96+ * <p> If the selector has already been closed then this method returns
97+ * immediately. Otherwise it marks the selector as closed and then invokes
98+ * the {@link #implCloseSelector implCloseSelector} method in order to
99+ * complete the close operation. </p>
100+ *
101+ * @throws IOException
102+ * If an I/O error occurs
103+ */
104+ public final void close() throws IOException {
105+ boolean open = selectorOpen.getAndSet(false);
106+ if (!open)
107+ return;
108+ implCloseSelector();
109+ }
110+
111+ /**
112+ * Closes this selector.
113+ *
114+ * <p> This method is invoked by the {@link #close close} method in order
115+ * to perform the actual work of closing the selector. This method is only
116+ * invoked if the selector has not yet been closed, and it is never invoked
117+ * more than once.
118+ *
119+ * <p> An implementation of this method must arrange for any other thread
120+ * that is blocked in a selection operation upon this selector to return
121+ * immediately as if by invoking the {@link
122+ * java.nio.channels.Selector#wakeup wakeup} method. </p>
123+ *
124+ * @throws IOException
125+ * If an I/O error occurs while closing the selector
126+ */
127+ protected abstract void implCloseSelector() throws IOException;
128+
129+ public final boolean isOpen() {
130+ return selectorOpen.get();
131+ }
132+
133+ /**
134+ * Returns the provider that created this channel.
135+ *
136+ * @return The provider that created this channel
137+ */
138+ public final SelectorProvider provider() {
139+ return provider;
140+ }
141+
142+ /**
143+ * Retrieves this selector's cancelled-key set.
144+ *
145+ * <p> This set should only be used while synchronized upon it. </p>
146+ *
147+ * @return The cancelled-key set
148+ */
149+ protected final Set<SelectionKey> cancelledKeys() {
150+ return cancelledKeys;
151+ }
152+
153+ /**
154+ * Registers the given channel with this selector.
155+ *
156+ * <p> This method is invoked by a channel's {@link
157+ * AbstractSelectableChannel#register register} method in order to perform
158+ * the actual work of registering the channel with this selector. </p>
159+ *
160+ * @param ch
161+ * The channel to be registered
162+ *
163+ * @param ops
164+ * The initial interest set, which must be valid
165+ *
166+ * @param att
167+ * The initial attachment for the resulting key
168+ *
169+ * @return A new key representing the registration of the given channel
170+ * with this selector
171+ */
172+ protected abstract SelectionKey register(AbstractSelectableChannel ch,
173+ int ops, Object att);
174+
175+ /**
176+ * Removes the given key from its channel's key set.
177+ *
178+ * <p> This method must be invoked by the selector for each channel that it
179+ * deregisters. </p>
180+ *
181+ * @param key
182+ * The selection key to be removed
183+ */
184+ protected final void deregister(AbstractSelectionKey key) {
185+ ((AbstractSelectableChannel)key.channel()).removeKey(key);
186+ }
187+
188+
189+ // -- Interruption machinery --
190+
191+ private Interruptible interruptor = null;
192+
193+ /**
194+ * Marks the beginning of an I/O operation that might block indefinitely.
195+ *
196+ * <p> This method should be invoked in tandem with the {@link #end end}
197+ * method, using a <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block as
198+ * shown <a href="#be">above</a>, in order to implement interruption for
199+ * this selector.
200+ *
201+ * <p> Invoking this method arranges for the selector's {@link
202+ * Selector#wakeup wakeup} method to be invoked if a thread's {@link
203+ * Thread#interrupt interrupt} method is invoked while the thread is
204+ * blocked in an I/O operation upon the selector. </p>
205+ */
206+ protected final void begin() {
207+ if (interruptor == null) {
208+ interruptor = new Interruptible() {
209+ public void interrupt(Thread ignore) {
210+ AbstractSelector.this.wakeup();
211+ }};
212+ }
213+ AbstractInterruptibleChannel.blockedOn(interruptor);
214+ Thread me = Thread.currentThread();
215+ if (me.isInterrupted())
216+ interruptor.interrupt(me);
217+ }
218+
219+ /**
220+ * Marks the end of an I/O operation that might block indefinitely.
221+ *
222+ * <p> This method should be invoked in tandem with the {@link #begin begin}
223+ * method, using a <tt>try</tt>&nbsp;...&nbsp;<tt>finally</tt> block as
224+ * shown <a href="#be">above</a>, in order to implement interruption for
225+ * this selector. </p>
226+ */
227+ protected final void end() {
228+ AbstractInterruptibleChannel.blockedOn(null);
229+ }
230+
231+}
java/pkg/java/nio/channels/spi/AsynchronousChannelProvider$ProviderHolder$1.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AsynchronousChannelProvider$ProviderHolder.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AsynchronousChannelProvider.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/AsynchronousChannelProvider.java+241−0
@@ -0,0 +1,241 @@
1+/*
2+ * Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels.spi;
27+
28+import java.nio.channels.*;
29+import java.io.IOException;
30+import java.util.Iterator;
31+import java.util.ServiceLoader;
32+import java.util.ServiceConfigurationError;
33+import java.util.concurrent.*;
34+import java.security.AccessController;
35+import java.security.PrivilegedAction;
36+
37+/**
38+ * Service-provider class for asynchronous channels.
39+ *
40+ * <p> An asynchronous channel provider is a concrete subclass of this class that
41+ * has a zero-argument constructor and implements the abstract methods specified
42+ * below. A given invocation of the Java virtual machine maintains a single
43+ * system-wide default provider instance, which is returned by the {@link
44+ * #provider() provider} method. The first invocation of that method will locate
45+ * the default provider as specified below.
46+ *
47+ * <p> All of the methods in this class are safe for use by multiple concurrent
48+ * threads. </p>
49+ *
50+ * @since 1.7
51+ */
52+
53+public abstract class AsynchronousChannelProvider {
54+ private static Void checkPermission() {
55+ SecurityManager sm = System.getSecurityManager();
56+ if (sm != null)
57+ sm.checkPermission(new RuntimePermission("asynchronousChannelProvider"));
58+ return null;
59+ }
60+ private AsynchronousChannelProvider(Void ignore) { }
61+
62+ /**
63+ * Initializes a new instance of this class.
64+ *
65+ * @throws SecurityException
66+ * If a security manager has been installed and it denies
67+ * {@link RuntimePermission}<tt>("asynchronousChannelProvider")</tt>
68+ */
69+ protected AsynchronousChannelProvider() {
70+ this(checkPermission());
71+ }
72+
73+ // lazy initialization of default provider
74+ private static class ProviderHolder {
75+ static final AsynchronousChannelProvider provider = load();
76+
77+ private static AsynchronousChannelProvider load() {
78+ return AccessController
79+ .doPrivileged(new PrivilegedAction<AsynchronousChannelProvider>() {
80+ public AsynchronousChannelProvider run() {
81+ AsynchronousChannelProvider p;
82+ p = loadProviderFromProperty();
83+ if (p != null)
84+ return p;
85+ p = loadProviderAsService();
86+ if (p != null)
87+ return p;
88+ return sun.nio.ch.DefaultAsynchronousChannelProvider.create();
89+ }});
90+ }
91+
92+ private static AsynchronousChannelProvider loadProviderFromProperty() {
93+ String cn = System.getProperty("java.nio.channels.spi.AsynchronousChannelProvider");
94+ if (cn == null)
95+ return null;
96+ try {
97+ Class<?> c = Class.forName(cn, true,
98+ ClassLoader.getSystemClassLoader());
99+ return (AsynchronousChannelProvider)c.newInstance();
100+ } catch (ClassNotFoundException x) {
101+ throw new ServiceConfigurationError(null, x);
102+ } catch (IllegalAccessException x) {
103+ throw new ServiceConfigurationError(null, x);
104+ } catch (InstantiationException x) {
105+ throw new ServiceConfigurationError(null, x);
106+ } catch (SecurityException x) {
107+ throw new ServiceConfigurationError(null, x);
108+ }
109+ }
110+
111+ private static AsynchronousChannelProvider loadProviderAsService() {
112+ ServiceLoader<AsynchronousChannelProvider> sl =
113+ ServiceLoader.load(AsynchronousChannelProvider.class,
114+ ClassLoader.getSystemClassLoader());
115+ Iterator<AsynchronousChannelProvider> i = sl.iterator();
116+ for (;;) {
117+ try {
118+ return (i.hasNext()) ? i.next() : null;
119+ } catch (ServiceConfigurationError sce) {
120+ if (sce.getCause() instanceof SecurityException) {
121+ // Ignore the security exception, try the next provider
122+ continue;
123+ }
124+ throw sce;
125+ }
126+ }
127+ }
128+ }
129+
130+ /**
131+ * Returns the system-wide default asynchronous channel provider for this
132+ * invocation of the Java virtual machine.
133+ *
134+ * <p> The first invocation of this method locates the default provider
135+ * object as follows: </p>
136+ *
137+ * <ol>
138+ *
139+ * <li><p> If the system property
140+ * <tt>java.nio.channels.spi.AsynchronousChannelProvider</tt> is defined
141+ * then it is taken to be the fully-qualified name of a concrete provider class.
142+ * The class is loaded and instantiated; if this process fails then an
143+ * unspecified error is thrown. </p></li>
144+ *
145+ * <li><p> If a provider class has been installed in a jar file that is
146+ * visible to the system class loader, and that jar file contains a
147+ * provider-configuration file named
148+ * <tt>java.nio.channels.spi.AsynchronousChannelProvider</tt> in the resource
149+ * directory <tt>META-INF/services</tt>, then the first class name
150+ * specified in that file is taken. The class is loaded and
151+ * instantiated; if this process fails then an unspecified error is
152+ * thrown. </p></li>
153+ *
154+ * <li><p> Finally, if no provider has been specified by any of the above
155+ * means then the system-default provider class is instantiated and the
156+ * result is returned. </p></li>
157+ *
158+ * </ol>
159+ *
160+ * <p> Subsequent invocations of this method return the provider that was
161+ * returned by the first invocation. </p>
162+ *
163+ * @return The system-wide default AsynchronousChannel provider
164+ */
165+ public static AsynchronousChannelProvider provider() {
166+ return ProviderHolder.provider;
167+ }
168+
169+ /**
170+ * Constructs a new asynchronous channel group with a fixed thread pool.
171+ *
172+ * @param nThreads
173+ * The number of threads in the pool
174+ * @param threadFactory
175+ * The factory to use when creating new threads
176+ *
177+ * @throws IllegalArgumentException
178+ * If {@code nThreads <= 0}
179+ * @throws IOException
180+ * If an I/O error occurs
181+ *
182+ * @see AsynchronousChannelGroup#withFixedThreadPool
183+ */
184+ public abstract AsynchronousChannelGroup
185+ openAsynchronousChannelGroup(int nThreads, ThreadFactory threadFactory) throws IOException;
186+
187+ /**
188+ * Constructs a new asynchronous channel group with the given thread pool.
189+ *
190+ * @param executor
191+ * The thread pool
192+ * @param initialSize
193+ * A value {@code >=0} or a negative value for implementation
194+ * specific default
195+ *
196+ * @throws IOException
197+ * If an I/O error occurs
198+ *
199+ * @see AsynchronousChannelGroup#withCachedThreadPool
200+ */
201+ public abstract AsynchronousChannelGroup
202+ openAsynchronousChannelGroup(ExecutorService executor, int initialSize) throws IOException;
203+
204+ /**
205+ * Opens an asynchronous server-socket channel.
206+ *
207+ * @param group
208+ * The group to which the channel is bound, or {@code null} to
209+ * bind to the default group
210+ *
211+ * @return The new channel
212+ *
213+ * @throws IllegalChannelGroupException
214+ * If the provider that created the group differs from this provider
215+ * @throws ShutdownChannelGroupException
216+ * The group is shutdown
217+ * @throws IOException
218+ * If an I/O error occurs
219+ */
220+ public abstract AsynchronousServerSocketChannel openAsynchronousServerSocketChannel
221+ (AsynchronousChannelGroup group) throws IOException;
222+
223+ /**
224+ * Opens an asynchronous socket channel.
225+ *
226+ * @param group
227+ * The group to which the channel is bound, or {@code null} to
228+ * bind to the default group
229+ *
230+ * @return The new channel
231+ *
232+ * @throws IllegalChannelGroupException
233+ * If the provider that created the group differs from this provider
234+ * @throws ShutdownChannelGroupException
235+ * The group is shutdown
236+ * @throws IOException
237+ * If an I/O error occurs
238+ */
239+ public abstract AsynchronousSocketChannel openAsynchronousSocketChannel
240+ (AsynchronousChannelGroup group) throws IOException;
241+}
java/pkg/java/nio/channels/spi/SelectorProvider$1.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/SelectorProvider.class+0−0

Binary file not shown.

java/pkg/java/nio/channels/spi/SelectorProvider.java+302−0
@@ -0,0 +1,302 @@
1+/*
2+ * Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+ *
5+ * This code is free software; you can redistribute it and/or modify it
6+ * under the terms of the GNU General Public License version 2 only, as
7+ * published by the Free Software Foundation. Oracle designates this
8+ * particular file as subject to the "Classpath" exception as provided
9+ * by Oracle in the LICENSE file that accompanied this code.
10+ *
11+ * This code is distributed in the hope that it will be useful, but WITHOUT
12+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ * version 2 for more details (a copy is included in the LICENSE file that
15+ * accompanied this code).
16+ *
17+ * You should have received a copy of the GNU General Public License version
18+ * 2 along with this work; if not, write to the Free Software Foundation,
19+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+ *
21+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ * or visit www.oracle.com if you need additional information or have any
23+ * questions.
24+ */
25+
26+package java.nio.channels.spi;
27+
28+import java.io.IOException;
29+import java.net.ProtocolFamily;
30+import java.nio.channels.*;
31+import java.security.AccessController;
32+import java.security.PrivilegedAction;
33+import java.util.Iterator;
34+import java.util.ServiceLoader;
35+import java.util.ServiceConfigurationError;
36+import sun.security.action.GetPropertyAction;
37+
38+
39+/**
40+ * Service-provider class for selectors and selectable channels.
41+ *
42+ * <p> A selector provider is a concrete subclass of this class that has a
43+ * zero-argument constructor and implements the abstract methods specified
44+ * below. A given invocation of the Java virtual machine maintains a single
45+ * system-wide default provider instance, which is returned by the {@link
46+ * #provider() provider} method. The first invocation of that method will locate
47+ * the default provider as specified below.
48+ *
49+ * <p> The system-wide default provider is used by the static <tt>open</tt>
50+ * methods of the {@link java.nio.channels.DatagramChannel#open
51+ * DatagramChannel}, {@link java.nio.channels.Pipe#open Pipe}, {@link
52+ * java.nio.channels.Selector#open Selector}, {@link
53+ * java.nio.channels.ServerSocketChannel#open ServerSocketChannel}, and {@link
54+ * java.nio.channels.SocketChannel#open SocketChannel} classes. It is also
55+ * used by the {@link java.lang.System#inheritedChannel System.inheritedChannel()}
56+ * method. A program may make use of a provider other than the default provider
57+ * by instantiating that provider and then directly invoking the <tt>open</tt>
58+ * methods defined in this class.
59+ *
60+ * <p> All of the methods in this class are safe for use by multiple concurrent
61+ * threads. </p>
62+ *
63+ *
64+ * @author Mark Reinhold
65+ * @author JSR-51 Expert Group
66+ * @since 1.4
67+ */
68+
69+public abstract class SelectorProvider {
70+
71+ private static final Object lock = new Object();
72+ private static SelectorProvider provider = null;
73+
74+ /**
75+ * Initializes a new instance of this class. </p>
76+ *
77+ * @throws SecurityException
78+ * If a security manager has been installed and it denies
79+ * {@link RuntimePermission}<tt>("selectorProvider")</tt>
80+ */
81+ protected SelectorProvider() {
82+ SecurityManager sm = System.getSecurityManager();
83+ if (sm != null)
84+ sm.checkPermission(new RuntimePermission("selectorProvider"));
85+ }
86+
87+ private static boolean loadProviderFromProperty() {
88+ String cn = System.getProperty("java.nio.channels.spi.SelectorProvider");
89+ if (cn == null)
90+ return false;
91+ try {
92+ Class<?> c = Class.forName(cn, true,
93+ ClassLoader.getSystemClassLoader());
94+ provider = (SelectorProvider)c.newInstance();
95+ return true;
96+ } catch (ClassNotFoundException x) {
97+ throw new ServiceConfigurationError(null, x);
98+ } catch (IllegalAccessException x) {
99+ throw new ServiceConfigurationError(null, x);
100+ } catch (InstantiationException x) {
101+ throw new ServiceConfigurationError(null, x);
102+ } catch (SecurityException x) {
103+ throw new ServiceConfigurationError(null, x);
104+ }
105+ }
106+
107+ private static boolean loadProviderAsService() {
108+
109+ ServiceLoader<SelectorProvider> sl =
110+ ServiceLoader.load(SelectorProvider.class,
111+ ClassLoader.getSystemClassLoader());
112+ Iterator<SelectorProvider> i = sl.iterator();
113+ for (;;) {
114+ try {
115+ if (!i.hasNext())
116+ return false;
117+ provider = i.next();
118+ return true;
119+ } catch (ServiceConfigurationError sce) {
120+ if (sce.getCause() instanceof SecurityException) {
121+ // Ignore the security exception, try the next provider
122+ continue;
123+ }
124+ throw sce;
125+ }
126+ }
127+ }
128+
129+ /**
130+ * Returns the system-wide default selector provider for this invocation of
131+ * the Java virtual machine.
132+ *
133+ * <p> The first invocation of this method locates the default provider
134+ * object as follows: </p>
135+ *
136+ * <ol>
137+ *
138+ * <li><p> If the system property
139+ * <tt>java.nio.channels.spi.SelectorProvider</tt> is defined then it is
140+ * taken to be the fully-qualified name of a concrete provider class.
141+ * The class is loaded and instantiated; if this process fails then an
142+ * unspecified error is thrown. </p></li>
143+ *
144+ * <li><p> If a provider class has been installed in a jar file that is
145+ * visible to the system class loader, and that jar file contains a
146+ * provider-configuration file named
147+ * <tt>java.nio.channels.spi.SelectorProvider</tt> in the resource
148+ * directory <tt>META-INF/services</tt>, then the first class name
149+ * specified in that file is taken. The class is loaded and
150+ * instantiated; if this process fails then an unspecified error is
151+ * thrown. </p></li>
152+ *
153+ * <li><p> Finally, if no provider has been specified by any of the above
154+ * means then the system-default provider class is instantiated and the
155+ * result is returned. </p></li>
156+ *
157+ * </ol>
158+ *
159+ * <p> Subsequent invocations of this method return the provider that was
160+ * returned by the first invocation. </p>
161+ *
162+ * @return The system-wide default selector provider
163+ */
164+ public static SelectorProvider provider() {
165+ synchronized (lock) {
166+ if (provider != null)
167+ return provider;
168+ return AccessController.doPrivileged(
169+ new PrivilegedAction<SelectorProvider>() {
170+ public SelectorProvider run() {
171+ if (loadProviderFromProperty())
172+ return provider;
173+ if (loadProviderAsService())
174+ return provider;
175+ provider = sun.nio.ch.DefaultSelectorProvider.create();
176+ return provider;
177+ }
178+ });
179+ }
180+ }
181+
182+ /**
183+ * Opens a datagram channel. </p>
184+ *
185+ * @return The new channel
186+ */
187+ public abstract DatagramChannel openDatagramChannel()
188+ throws IOException;
189+
190+ /**
191+ * Opens a datagram channel.
192+ *
193+ * @param family
194+ * The protocol family
195+ *
196+ * @return A new datagram channel
197+ *
198+ * @throws UnsupportedOperationException
199+ * If the specified protocol family is not supported
200+ * @throws IOException
201+ * If an I/O error occurs
202+ *
203+ * @since 1.7
204+ */
205+ public abstract DatagramChannel openDatagramChannel(ProtocolFamily family)
206+ throws IOException;
207+
208+ /**
209+ * Opens a pipe. </p>
210+ *
211+ * @return The new pipe
212+ */
213+ public abstract Pipe openPipe()
214+ throws IOException;
215+
216+ /**
217+ * Opens a selector. </p>
218+ *
219+ * @return The new selector
220+ */
221+ public abstract AbstractSelector openSelector()
222+ throws IOException;
223+
224+ /**
225+ * Opens a server-socket channel. </p>
226+ *
227+ * @return The new channel
228+ */
229+ public abstract ServerSocketChannel openServerSocketChannel()
230+ throws IOException;
231+
232+ /**
233+ * Opens a socket channel. </p>
234+ *
235+ * @return The new channel
236+ */
237+ public abstract SocketChannel openSocketChannel()
238+ throws IOException;
239+
240+ /**
241+ * Returns the channel inherited from the entity that created this
242+ * Java virtual machine.
243+ *
244+ * <p> On many operating systems a process, such as a Java virtual
245+ * machine, can be started in a manner that allows the process to
246+ * inherit a channel from the entity that created the process. The
247+ * manner in which this is done is system dependent, as are the
248+ * possible entities to which the channel may be connected. For example,
249+ * on UNIX systems, the Internet services daemon (<i>inetd</i>) is used to
250+ * start programs to service requests when a request arrives on an
251+ * associated network port. In this example, the process that is started,
252+ * inherits a channel representing a network socket.
253+ *
254+ * <p> In cases where the inherited channel represents a network socket
255+ * then the {@link java.nio.channels.Channel Channel} type returned
256+ * by this method is determined as follows:
257+ *
258+ * <ul>
259+ *
260+ * <li><p> If the inherited channel represents a stream-oriented connected
261+ * socket then a {@link java.nio.channels.SocketChannel SocketChannel} is
262+ * returned. The socket channel is, at least initially, in blocking
263+ * mode, bound to a socket address, and connected to a peer.
264+ * </p></li>
265+ *
266+ * <li><p> If the inherited channel represents a stream-oriented listening
267+ * socket then a {@link java.nio.channels.ServerSocketChannel
268+ * ServerSocketChannel} is returned. The server-socket channel is, at
269+ * least initially, in blocking mode, and bound to a socket address.
270+ * </p></li>
271+ *
272+ * <li><p> If the inherited channel is a datagram-oriented socket
273+ * then a {@link java.nio.channels.DatagramChannel DatagramChannel} is
274+ * returned. The datagram channel is, at least initially, in blocking
275+ * mode, and bound to a socket address.
276+ * </p></li>
277+ *
278+ * </ul>
279+ *
280+ * <p> In addition to the network-oriented channels described, this method
281+ * may return other kinds of channels in the future.
282+ *
283+ * <p> The first invocation of this method creates the channel that is
284+ * returned. Subsequent invocations of this method return the same
285+ * channel. </p>
286+ *
287+ * @return The inherited channel, if any, otherwise <tt>null</tt>.
288+ *
289+ * @throws IOException
290+ * If an I/O error occurs
291+ *
292+ * @throws SecurityException
293+ * If a security manager has been installed and it denies
294+ * {@link RuntimePermission}<tt>("inheritedChannel")</tt>
295+ *
296+ * @since 1.5
297+ */
298+ public Channel inheritedChannel() throws IOException {
299+ return null;
300+ }
301+
302+}
java/pkg/java/nio/channels/spi/mkfile+13−0
@@ -0,0 +1,13 @@
1+<../../../../../../mkconfig
2+
3+TARG=\
4+ AbstractInterruptibleChannel.dis\
5+ AbstractSelectableChannel.dis\
6+ AbstractSelectionKey.dis\
7+ AbstractSelector.dis\
8+ AsynchronousChannelProvider.dis\
9+ SelectorProvider.dis\
10+
11+DISBIN=$ROOT/java/dis/java/java/java/nio/channels/spi
12+
13+<$ROOT/mkfiles/mkjava
java/pkg/java/nio/channels/spi/package.html+45−0
@@ -0,0 +1,45 @@
1+<!--
2+ Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
3+ DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
5+ This code is free software; you can redistribute it and/or modify it
6+ under the terms of the GNU General Public License version 2 only, as
7+ published by the Free Software Foundation. Oracle designates this
8+ particular file as subject to the "Classpath" exception as provided
9+ by Oracle in the LICENSE file that accompanied this code.
10+
11+ This code is distributed in the hope that it will be useful, but WITHOUT
12+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13+ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14+ version 2 for more details (a copy is included in the LICENSE file that
15+ accompanied this code).
16+
17+ You should have received a copy of the GNU General Public License version
18+ 2 along with this work; if not, write to the Free Software Foundation,
19+ Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20+
21+ Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22+ or visit www.oracle.com if you need additional information or have any
23+ questions.
24+-->
25+
26+<!doctype html public "-//IETF//DTD HTML//EN">
27+<html>
28+<body bgcolor="white">
29+
30+Service-provider classes for the <tt>{@link java.nio.channels}</tt> package.
31+
32+<p> Only developers who are defining new selector providers or asynchronous
33+channel providers should need to make direct use of this package. </p>
34+
35+<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
36+or method in any class or interface in this package will cause a {@link
37+java.lang.NullPointerException NullPointerException} to be thrown.
38+
39+
40+@since 1.4
41+@author Mark Reinhold
42+@author JSR-51 Expert Group
43+
44+</body>
45+</html>

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t