public interface ApiChannel
extends java.nio.channels.Channel, java.lang.AutoCloseable
The ApiChannel interface exposes the lowest possible level of detail when writing/reading messages from the API by still abstracting away the details of connection establishment, TLS handshaking and so on.
The interface can be used in the cases where the flows using the Call and MultiCall abstractions may yield a considerable amount of memory allocations, usually when making a chain of repeating requests. The contract does not restrict in any way how the requests will be written, so request pipelining can be implemented by writing multiple requests at once, without immediately reading the responses, which may result in considerable speed improvements.
If otherwise stated, instances of this interface will not be thread-safe and reading/writing at the same time from multiple threads will result in undetermined behavior. All implementations should allow calling close() from multiple threads multiple times.
Calling close() on an idle ApiChannel instance will result in connection recycling,
for other cases the underlying socket will be closed.
A ApiChannel instance is considered idle when the number of sent requests is equal
to the number of fully read responses.
Each successful call to ProtocolRequestWriter.endRequest() is counted as a sent request.
A fully read response is counted after each successful call to ProtocolResponseReader.endResponse()
for non-data responses or to ProtocolResponseReader.readData(BufferedSink) for data-containing responses.
Instances can be obtained via the PCloudAPIClient.newChannel(Endpoint) and PCloudAPIClient.newChannel() methods.
| Modifier and Type | Method and Description |
|---|---|
void |
close()
|
Endpoint |
endpoint() |
boolean |
isIdle()
Check whether the channel is idle
|
ProtocolResponseReader |
reader() |
ProtocolRequestWriter |
writer() |
ProtocolResponseReader reader()
ProtocolRequestWriter writer()
boolean isIdle()
An ApiChannel is idle when the number of completed requests equals the number of completely read responses.
A fresh ApiChannel instance will always be idle.
The return value for already closed ApiChannel instances is undetermined.
true if channel is idle, false otherwise.void close()
close in interface java.lang.AutoCloseableclose in interface java.nio.channels.Channelclose in interface java.io.Closeable