[jira] [Commented] (OAK-1331) MicroKernel API: clarify semantics of `read` method

["Thomas Mueller (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/OAK-1331?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13876244#comment-13876244 ] 

Thomas Mueller commented on OAK-1331:
-------------------------------------

I think it makes sense. It should reduce the number of network roundtrips (no need to read the length), and it should also reduce the probability of bugs.

The documentation could also say "If the return value is lower than the requested value, no more data is available. This method never returns negative values".



> MicroKernel API: clarify semantics of `read` method
> ---------------------------------------------------
>
>                 Key: OAK-1331
>                 URL: https://issues.apache.org/jira/browse/OAK-1331
>             Project: Jackrabbit Oak
>          Issue Type: Improvement
>          Components: mk, mongomk, segmentmk
>            Reporter: Stefan Guggisberg
>             Fix For: 0.15
>
>
> the javadoc of {{MicroKernel#read}} currently states that 
> {quote}
> An attempt is made to read as many as {{length}} bytes, but a smaller number may be read.
> {quote}
> under what conditions a smaller amount might be read is not specified. 
> with the current specification an api consumer would either have to know the length of the blob in advance (i.e. by calling  {{MicroKernel#getLength}}) or  would need to call the {{MicroKernel#read}} method twice to make sure that the blob content is fully read. 
> i suggest to clarify the contract as follows:
> Reads up to {{length}} bytes of data from the specified blob into the given array of bytes where the actual number of bytes read is {{min(length, max(0, blobLength - pos))}}.



--
This message was sent by Atlassian JIRA
(v6.1.5#6160)