[OAK-1331] MicroKernel API: clarify semantics of `read` method

• Type: Improvement
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 0.17
• Component/s: mk, mongomk, segmentmk
• Labels: documentation
• Assignee: Stefan Guggisberg
• Reporter: Stefan Guggisberg
• Created: 16/Jan/14 14:56
• Updated: 27/Feb/14 09:28
• Resolved: 11/Feb/14 10:23

Description

the javadoc of MicroKernel#read currently states that

An attempt is made to read as many as length bytes, but a smaller number may be read.

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)).

Issue Links

• is part of: OAK-11 Document and tighten contract of Microkernel API