Attempts to decode SSL/TLS network data into a subsequence of
plaintext application data buffers. This <i>"scattering"</i>
operation decodes, in a single invocation, a sequence of bytes
into one or more of a given sequence of buffers. Scattering
unwraps are often useful when implementing network protocols or
file formats that, for example, group data into segments
consisting of one or more fixed-length headers followed by a
variable-length body. See
{@link java.nio.channels.ScatteringByteChannel} for more
information on scattering, and {@link
java.nio.channels.ScatteringByteChannel#read(ByteBuffer[],
int, int)} for more information on the subsequence
behavior.
<P>
Depending on the state of the SSLEngine, this method may consume
network data without producing any application data (for example,
it may consume handshake data.)
<P>
The application is responsible for reliably obtaining the network
data from the peer, and for invoking unwrap() on the data in the
order it was received. The application must properly synchronize
multiple calls to this method.
<P>
If this <code>SSLEngine</code> has not yet started its initial
handshake, this method will automatically start the handshake.
<P>
This method will attempt to consume one complete SSL/TLS network
packet, but will never consume more than the sum of the bytes
remaining in the buffers. Each <code>ByteBuffer</code>'s
position is updated to reflect the amount of data consumed or
produced. The limits remain the same.
<P>
The underlying memory used by the <code>src</code> and
<code>dsts ByteBuffer</code>s must not be the same.
<P>
The inbound network buffer may be modified as a result of this
call: therefore if the network data packet is required for some
secondary purpose, the data should be duplicated before calling this
method. Note: the network data will not be useful to a second
SSLEngine, as each SSLEngine contains unique random state which
influences the SSL/TLS messages.
<P>
See the class description for more information on engine closure.
@param src
a <code>ByteBuffer</code> containing inbound network data.
@param dsts
an array of <code>ByteBuffer</code>s to hold inbound
application data.
@param offset
The offset within the buffer array of the first buffer from
which bytes are to be transferred; it must be non-negative
and no larger than <code>dsts.length</code>.
@param length
The maximum number of buffers to be accessed; it must be
non-negative and no larger than
<code>dsts.length</code> - <code>offset</code>.
@return an <code>SSLEngineResult</code> describing the result
of this operation.
@throws SSLException
A problem was encountered while processing the
data that caused the <code>SSLEngine</code> to abort.
See the class description for more information on
engine closure.
@throws IndexOutOfBoundsException
If the preconditions on the <code>offset</code> and
<code>length</code> parameters do not hold.
@throws ReadOnlyBufferException
if any of the <code>dst</code> buffers are read-only.
@throws IllegalArgumentException
if either <code>src</code> or <code>dsts</code>
is null, or if any element in the <code>dsts</code>
subsequence specified is null.
@throws IllegalStateException if the client/server mode
has not yet been set.
@see java.nio.channels.ScatteringByteChannel
@see java.nio.channels.ScatteringByteChannel#read(
ByteBuffer[], int, int)
Attempts to decode SSL/TLS network data into a subsequence of plaintext application data buffers. This <i>"scattering"</i> operation decodes, in a single invocation, a sequence of bytes into one or more of a given sequence of buffers. Scattering unwraps are often useful when implementing network protocols or file formats that, for example, group data into segments consisting of one or more fixed-length headers followed by a variable-length body. See {@link java.nio.channels.ScatteringByteChannel} for more information on scattering, and {@link java.nio.channels.ScatteringByteChannel#read(ByteBuffer[], int, int)} for more information on the subsequence behavior. <P> Depending on the state of the SSLEngine, this method may consume network data without producing any application data (for example, it may consume handshake data.) <P> The application is responsible for reliably obtaining the network data from the peer, and for invoking unwrap() on the data in the order it was received. The application must properly synchronize multiple calls to this method. <P> If this <code>SSLEngine</code> has not yet started its initial handshake, this method will automatically start the handshake. <P> This method will attempt to consume one complete SSL/TLS network packet, but will never consume more than the sum of the bytes remaining in the buffers. Each <code>ByteBuffer</code>'s position is updated to reflect the amount of data consumed or produced. The limits remain the same. <P> The underlying memory used by the <code>src</code> and <code>dsts ByteBuffer</code>s must not be the same. <P> The inbound network buffer may be modified as a result of this call: therefore if the network data packet is required for some secondary purpose, the data should be duplicated before calling this method. Note: the network data will not be useful to a second SSLEngine, as each SSLEngine contains unique random state which influences the SSL/TLS messages. <P> See the class description for more information on engine closure.
@param src a <code>ByteBuffer</code> containing inbound network data. @param dsts an array of <code>ByteBuffer</code>s to hold inbound application data. @param offset The offset within the buffer array of the first buffer from which bytes are to be transferred; it must be non-negative and no larger than <code>dsts.length</code>. @param length The maximum number of buffers to be accessed; it must be non-negative and no larger than <code>dsts.length</code> - <code>offset</code>. @return an <code>SSLEngineResult</code> describing the result of this operation. @throws SSLException A problem was encountered while processing the data that caused the <code>SSLEngine</code> to abort. See the class description for more information on engine closure. @throws IndexOutOfBoundsException If the preconditions on the <code>offset</code> and <code>length</code> parameters do not hold. @throws ReadOnlyBufferException if any of the <code>dst</code> buffers are read-only. @throws IllegalArgumentException if either <code>src</code> or <code>dsts</code> is null, or if any element in the <code>dsts</code> subsequence specified is null. @throws IllegalStateException if the client/server mode has not yet been set. @see java.nio.channels.ScatteringByteChannel @see java.nio.channels.ScatteringByteChannel#read( ByteBuffer[], int, int)