Attempts to encode plaintext bytes from a subsequence of data
buffers into SSL/TLS network data. This <i>"gathering"</i>
operation encodes, in a single invocation, a sequence of bytes
from one or more of a given sequence of buffers. Gathering
wraps 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.GatheringByteChannel} for more
information on gathering, and {@link
java.nio.channels.GatheringByteChannel#write(ByteBuffer[],
int, int)} for more information on the subsequence
behavior.
<P>
Depending on the state of the SSLEngine, this method may produce
network data without consuming any application data (for example,
it may generate handshake data.)
<P>
The application is responsible for reliably transporting the
network data to the peer, and for ensuring that data created by
multiple calls to wrap() is transported in the same order in which
it was generated. 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 produce SSL/TLS records, and will
consume as much source data as possible, but will never consume
more than the sum of the bytes remaining in each buffer. 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>srcs</code> and
<code>dst ByteBuffer</code>s must not be the same.
<P>
See the class description for more information on engine closure.
@param srcs
an array of <code>ByteBuffers</code> containing the
outbound application data
@param offset
The offset within the buffer array of the first buffer from
which bytes are to be retrieved; it must be non-negative
and no larger than <code>srcs.length</code>
@param length
The maximum number of buffers to be accessed; it must be
non-negative and no larger than
<code>srcs.length</code> - <code>offset</code>
@param dst
a <code>ByteBuffer</code> to hold outbound network data
@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 the <code>dst</code> buffer is read-only.
@throws IllegalArgumentException
if either <code>srcs</code> or <code>dst</code>
is null, or if any element in the <code>srcs</code>
subsequence specified is null.
@throws IllegalStateException if the client/server mode
has not yet been set.
@see java.nio.channels.GatheringByteChannel
@see java.nio.channels.GatheringByteChannel#write(
ByteBuffer[], int, int)
Attempts to encode plaintext bytes from a subsequence of data buffers into SSL/TLS network data. This <i>"gathering"</i> operation encodes, in a single invocation, a sequence of bytes from one or more of a given sequence of buffers. Gathering wraps 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.GatheringByteChannel} for more information on gathering, and {@link java.nio.channels.GatheringByteChannel#write(ByteBuffer[], int, int)} for more information on the subsequence behavior. <P> Depending on the state of the SSLEngine, this method may produce network data without consuming any application data (for example, it may generate handshake data.) <P> The application is responsible for reliably transporting the network data to the peer, and for ensuring that data created by multiple calls to wrap() is transported in the same order in which it was generated. 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 produce SSL/TLS records, and will consume as much source data as possible, but will never consume more than the sum of the bytes remaining in each buffer. 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>srcs</code> and <code>dst ByteBuffer</code>s must not be the same. <P> See the class description for more information on engine closure.
@param srcs an array of <code>ByteBuffers</code> containing the outbound application data @param offset The offset within the buffer array of the first buffer from which bytes are to be retrieved; it must be non-negative and no larger than <code>srcs.length</code> @param length The maximum number of buffers to be accessed; it must be non-negative and no larger than <code>srcs.length</code> - <code>offset</code> @param dst a <code>ByteBuffer</code> to hold outbound network data @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 the <code>dst</code> buffer is read-only. @throws IllegalArgumentException if either <code>srcs</code> or <code>dst</code> is null, or if any element in the <code>srcs</code> subsequence specified is null. @throws IllegalStateException if the client/server mode has not yet been set. @see java.nio.channels.GatheringByteChannel @see java.nio.channels.GatheringByteChannel#write( ByteBuffer[], int, int)