AsynchronousChannel
Stay organized with collections
Save and categorize content based on your preferences.
Known Indirect Subclasses
|
A channel that supports asynchronous I/O operations. Asynchronous I/O
operations will usually take one of two forms:
Future
<V> operation(...)
void operation(... A attachment, CompletionHandler
<V,? super A> handler)
where
operation is the name of the I/O operation (read or write for
example),
V is the result type of the I/O operation, and
A is
the type of an object attached to the I/O operation to provide context when
consuming the result. The attachment is important for cases where a
state-less CompletionHandler
is used to consume the result
of many I/O operations.
In the first form, the methods defined by the Future
interface may be used to check if the operation has completed, wait for its
completion, and to retrieve the result. In the second form, a CompletionHandler
is invoked to consume the result of the I/O operation when
it completes or fails.
A channel that implements this interface is asynchronously
closeable: If an I/O operation is outstanding on the channel and the
channel's close
method is invoked, then the I/O operation
fails with the exception AsynchronousCloseException
.
Asynchronous channels are safe for use by multiple concurrent threads.
Some channel implementations may support concurrent reading and writing, but
may not allow more than one read and one write operation to be outstanding at
any given time.
Cancellation
The Future
interface defines the cancel
method to cancel execution. This causes all threads waiting on the result of
the I/O operation to throw CancellationException
.
Whether the underlying I/O operation can be cancelled is highly implementation
specific and therefore not specified. Where cancellation leaves the channel,
or the entity to which it is connected, in an inconsistent state, then the
channel is put into an implementation specific error state that
prevents further attempts to initiate I/O operations that are similar
to the operation that was cancelled. For example, if a read operation is
cancelled but the implementation cannot guarantee that bytes have not been
read from the channel then it puts the channel into an error state; further
attempts to initiate a read
operation cause an unspecified runtime
exception to be thrown. Similarly, if a write operation is cancelled but the
implementation cannot guarantee that bytes have not been written to the
channel then subsequent attempts to initiate a write
will fail with
an unspecified runtime exception.
Where the cancel
method is invoked with the mayInterruptIfRunning
parameter set to true
then the I/O operation
may be interrupted by closing the channel. In that case all threads waiting
on the result of the I/O operation throw CancellationException
and
any other I/O operations outstanding on the channel complete with the
exception AsynchronousCloseException
.
Where the cancel
method is invoked to cancel read or write
operations then it is recommended that all buffers used in the I/O operations
be discarded or care taken to ensure that the buffers are not accessed while
the channel remains open.
Public Method Summary
abstract
void
|
close()
Closes this channel.
|
Inherited Method Summary
From interface
java.io.Closeable
abstract
void
|
close()
Closes this stream and releases any system resources associated
with it.
|
Public Methods
public
abstract
void
close
()
Closes this channel.
Any outstanding asynchronous operations upon this channel will
complete with the exception AsynchronousCloseException
. After a
channel is closed, further attempts to initiate asynchronous I/O
operations complete immediately with cause ClosedChannelException
.
This method otherwise behaves exactly as specified by the Channel
interface.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-07-10 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-07-10 UTC."],[[["\u003cp\u003e\u003ccode\u003eAsynchronousChannel\u003c/code\u003e supports asynchronous I/O operations, using either Futures or CompletionHandlers for result handling.\u003c/p\u003e\n"],["\u003cp\u003eIt offers two forms for asynchronous operations: one using \u003ccode\u003eFuture\u003c/code\u003e for checking completion and retrieving results, and another using \u003ccode\u003eCompletionHandler\u003c/code\u003e for consuming results.\u003c/p\u003e\n"],["\u003cp\u003eClosing an \u003ccode\u003eAsynchronousChannel\u003c/code\u003e with outstanding operations results in those operations failing with \u003ccode\u003eAsynchronousCloseException\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eWhile generally thread-safe, specific implementations may have limitations on concurrent reading and writing.\u003c/p\u003e\n"],["\u003cp\u003eCancelling operations via \u003ccode\u003eFuture.cancel()\u003c/code\u003e may lead to an implementation-specific error state, affecting similar future operations.\u003c/p\u003e\n"]]],[],null,["# AsynchronousChannel\n\npublic interface **AsynchronousChannel** implements [Channel](../../../../reference/java/nio/channels/Channel.html) \n\n|---|---|---|\n| Known Indirect Subclasses [AsynchronousByteChannel](../../../../reference/java/nio/channels/AsynchronousByteChannel.html), [AsynchronousFileChannel](../../../../reference/java/nio/channels/AsynchronousFileChannel.html), [AsynchronousServerSocketChannel](../../../../reference/java/nio/channels/AsynchronousServerSocketChannel.html), [AsynchronousSocketChannel](../../../../reference/java/nio/channels/AsynchronousSocketChannel.html) |-----------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [AsynchronousByteChannel](../../../../reference/java/nio/channels/AsynchronousByteChannel.html) | An asynchronous channel that can read and write bytes. | | [AsynchronousFileChannel](../../../../reference/java/nio/channels/AsynchronousFileChannel.html) | An asynchronous channel for reading, writing, and manipulating a file. | | [AsynchronousServerSocketChannel](../../../../reference/java/nio/channels/AsynchronousServerSocketChannel.html) | An asynchronous channel for stream-oriented listening sockets. | | [AsynchronousSocketChannel](../../../../reference/java/nio/channels/AsynchronousSocketChannel.html) | An asynchronous channel for stream-oriented connecting sockets. | |||\n\nA channel that supports asynchronous I/O operations. Asynchronous I/O\noperations will usually take one of two forms:\n\n1.\n\n ../../../../reference/java/util/concurrent/Future.html\u003cV\u003e operation(...)\n\n2.\n\n void operation(... A attachment, ../../../../reference/java/nio/channels/CompletionHandler.html\u003cV,? super A\u003e handler)\n\nwhere *operation* is the name of the I/O operation (read or write for example), *V* is the result type of the I/O operation, and *A* is the type of an object attached to the I/O operation to provide context when consuming the result. The attachment is important for cases where a *state-less* `CompletionHandler` is used to consume the result of many I/O operations.\n\nIn the first form, the methods defined by the [Future](../../../../reference/java/util/concurrent/Future.html)\ninterface may be used to check if the operation has completed, wait for its\ncompletion, and to retrieve the result. In the second form, a [CompletionHandler](../../../../reference/java/nio/channels/CompletionHandler.html) is invoked to consume the result of the I/O operation when\nit completes or fails.\n\nA channel that implements this interface is *asynchronously\ncloseable* : If an I/O operation is outstanding on the channel and the\nchannel's [close](../../../../reference/java/nio/channels/AsynchronousChannel.html#close()) method is invoked, then the I/O operation\nfails with the exception [AsynchronousCloseException](../../../../reference/java/nio/channels/AsynchronousCloseException.html).\n\nAsynchronous channels are safe for use by multiple concurrent threads.\nSome channel implementations may support concurrent reading and writing, but\nmay not allow more than one read and one write operation to be outstanding at\nany given time.\n\nCancellation\n------------\n\nThe `Future` interface defines the [cancel](../../../../reference/java/util/concurrent/Future.html#cancel(boolean))\nmethod to cancel execution. This causes all threads waiting on the result of\nthe I/O operation to throw [CancellationException](../../../../reference/java/util/concurrent/CancellationException.html).\nWhether the underlying I/O operation can be cancelled is highly implementation\nspecific and therefore not specified. Where cancellation leaves the channel,\nor the entity to which it is connected, in an inconsistent state, then the\nchannel is put into an implementation specific *error state* that\nprevents further attempts to initiate I/O operations that are *similar*\nto the operation that was cancelled. For example, if a read operation is\ncancelled but the implementation cannot guarantee that bytes have not been\nread from the channel then it puts the channel into an error state; further\nattempts to initiate a `read` operation cause an unspecified runtime\nexception to be thrown. Similarly, if a write operation is cancelled but the\nimplementation cannot guarantee that bytes have not been written to the\nchannel then subsequent attempts to initiate a `write` will fail with\nan unspecified runtime exception.\n\nWhere the [cancel](../../../../reference/java/util/concurrent/Future.html#cancel(boolean)) method is invoked with the `mayInterruptIfRunning` parameter set to `true` then the I/O operation\nmay be interrupted by closing the channel. In that case all threads waiting\non the result of the I/O operation throw `CancellationException` and\nany other I/O operations outstanding on the channel complete with the\nexception [AsynchronousCloseException](../../../../reference/java/nio/channels/AsynchronousCloseException.html).\n\nWhere the `cancel` method is invoked to cancel read or write\noperations then it is recommended that all buffers used in the I/O operations\nbe discarded or care taken to ensure that the buffers are not accessed while\nthe channel remains open. \n\n### Public Method Summary\n\n|---------------|----------------------------------------------------------------------------------------------------------|\n| abstract void | [close](../../../../reference/java/nio/channels/AsynchronousChannel.html#close())() Closes this channel. |\n\n### Inherited Method Summary\n\nFrom interface [java.nio.channels.Channel](../../../../reference/java/nio/channels/Channel.html) \n\n|------------------|----------------------------------------------------------------------------------------------------------------------|\n| abstract void | [close](../../../../reference/java/nio/channels/Channel.html#close())() Closes this channel. |\n| abstract boolean | [isOpen](../../../../reference/java/nio/channels/Channel.html#isOpen())() Tells whether or not this channel is open. |\n\nFrom interface [java.io.Closeable](../../../../reference/java/io/Closeable.html) \n\n|---------------|------------------------------------------------------------------------------------------------------------------------------------------|\n| abstract void | [close](../../../../reference/java/io/Closeable.html#close())() Closes this stream and releases any system resources associated with it. |\n\nFrom interface [java.lang.AutoCloseable](../../../../reference/java/lang/AutoCloseable.html) \n\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------|\n| abstract void | [close](../../../../reference/java/lang/AutoCloseable.html#close())() Closes this resource, relinquishing any underlying resources. |\n\nPublic Methods\n--------------\n\n#### public abstract void\n**close**\n()\n\nCloses this channel.\n\nAny outstanding asynchronous operations upon this channel will\ncomplete with the exception [AsynchronousCloseException](../../../../reference/java/nio/channels/AsynchronousCloseException.html). After a\nchannel is closed, further attempts to initiate asynchronous I/O\noperations complete immediately with cause [ClosedChannelException](../../../../reference/java/nio/channels/ClosedChannelException.html).\n\nThis method otherwise behaves exactly as specified by the [Channel](../../../../reference/java/nio/channels/Channel.html) interface. \n\n##### Throws\n\n| [IOException](../../../../reference/java/io/IOException.html) | If an I/O error occurs |\n|---------------------------------------------------------------|------------------------|"]]