Sergey,
You are correct that is does look a little weird and that the spec is not exactly clear on the lifecycle of the buffer.
I think a lot of other containers just always do the copy, but we like to avoid that if possible so we have taken the approach that "ownership" of the buffer is effectively passed to jetty once the write call is made. The "ownership" is only passed back to the caller once they know the write is complete.... and they only know the write is complete if they are told by isReady() that another write can be performed.
Note that you can structure your code so that it does not looks so strange as typically the writes should be done in a loop something like:
void onWritePossible()
{
while (out.isReady())
{
if (prepareSomeContent(buffer))
out.write(buffer);
else
returnBuffer(buffer);
}
}
So a buffer is only reused just before the next write is attempted.
It is a compromise in complexity, but I think it is the best we can do with the API and the benefits of avoiding copies are worth it.
cheers
