An ArrayInputRecordStream object represents an array of Record objects opened for sequential read access. Opening takes place implicitly when an object is generated (see "Opening and closing"), but has no further meaning here as it would with files.
The ArrayInputRecordStream class offers methods for reading and skipping records. The method group for positioning is also supported in full.
Within the array from which is read a current read position is always defined at which the next read operation is performed. The current read position is defined by the number of the record in the array, the numbering of the records starting with zero. After opening, the current read position is zero.
Opening and closing
When an ArrayInputRecordStream object is constructed, the calling program provides the array with data records which are to be read later. This array is used directly and not copied, in other words any manipulations on this array or the records contained in it have a direct affect on the ArrayInputRecordStream object. With a second variant of the constructor the user can make part of an array with records (defined by offset and length) available for input.
The close() methods is present, but has no function for this class.
Methods for reading records
The read method is offered in two variants, one in which the record read is provided as a result in a newly generated Record object, and a second in which a Record object transferred by the calling program as an argument is filled with the data of the record read.
When a record buffer is created, it has precisely the same size as the data read. If the calling program provides the Record object, it must ensure that the record buffer is large enough to contain the data of the record to be read. If the specified record buffer is too small to contain all the data, an exception is triggered and no data is transferred.
The read() methods read the record at the current read position. The current read position is subsequently incremented by one, in other words the next record in the array is automatically positioned on.
The skip() method enables the specified number of records in the array to be skipped. It may be the case that it is not possible to skip exactly the number of records specified because the array no longer contains enough records. The return value of skip() specifies the actual number of records that are skipped.
The available() method returns the number of records which can still be read before the end of the array is reached. Reading from an array of records never leads to wait states.
Methods for positioning
The markSupported() method provides information on whether marking or repositioning is supported for this data stream. In this class this method always returns true.
The mark() method notes the current read position so as to be able to reposition to it later. The argument envisaged for mark() is ignored in this implementation and should always be specified as 0.
Calling reset() repositions the pointer to a read position previously noted with mark().