[jira] [Commented] (HADOOP-9495) Define behaviour of Seekable.seek(), write tests, fix all hadoop implementations for compliance

["Steve Loughran (JIRA)" <ji...@apache.org>]

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

Steve Loughran commented on HADOOP-9495:
----------------------------------------

h2. Requirements of implementations of {{Seekable}},{{PositionedReadable}} and {{InputStream}} (including all subclasses of {{FSInputStream}})

h3. Core seek requirements
* SEEK0: Implicit: all operations complete, successfully or unsuccessfully, within a bounded time period or throw an {{IOException}}
* SEEK1: When a file is opened, {{getPos()==0}} 
* SEEK2: Implementations MAY NOT implement {{seek()}}, and instead MAY throw an {{IOException}}. If this is the case, the SEEK4-7 and SEEK-READ2 & SEEK-READ3 are not required.
* SEEK3: A {{seek(L)}} on a closed input stream MUST fail with an {{IOException}}.
* SEEK4: On a {{seek(L)}} with {{L<0}} an exception MUST be thrown. It SHOULD be an {{IOException}}. It MAY be {{IllegalArgumentException}} or other {{RuntimeException}}
* SEEK5: On a {{seek(L)}} with {{L>length(file), an {{IOException}} MAY be thrown. It SHOULD be an {{EOFException}}
* SEEK6: On a {{seek(L)}} with {{L>length(file) If an {{IOException}} is not thrown, then an {{IOException}} MUST be thrown on the next {{read()}} operation. It SHOULD be an {{EOFException}}
* SEEK7: On a {{seek(L)}} with {{L >=0 && L<=length(file)}}, {{getPos()==L}}

SEEK6 is a relaxation of the {{Seekable.seek()}} definition, which states "Can't seek past the end of the file.". The {{RawLocalFileSystem}} on which everything ultimately depends does support seeking past the end of the file -it is only on the {{read()}} operation where an exception is raised.


h3. Seek and Read
* SEEK-READ1: After a {{read()}} operation where {{getPos()==L && L<length(file)}}, {{getPos()==L+1}}
* SEEK-READ2: After a {{seek(L)}} with {{L<length(file)}}, {{read()}} returns the byte at position L in the file.
* SEEK-READ3: After a {{seek(L)}} with {{L==length(file)}}, {{read()}} returns -1
* SEEK-READ4: After a {{seek(L)}} with {{L<=length(file)}}, {{read(byte[1],0,1)}} returns the byte at position L in the file.

h3. Seek and PositionedReadable Integration

* SEEK-READ5: {{PositionedReadable.read*(L) && length(file) > 0 => IOException}} (ideally, {{EOFException}}).
* SEEK-READ6: After a {{PositionedReadable.read*(L) where L< 0 => IOException. ({})
* SEEK-READ7: After any of the {{PositionedReadable.read*}} operations, {{getPos()}} is unchanged.

                
> Define behaviour of Seekable.seek(), write tests, fix all hadoop implementations for compliance
> -----------------------------------------------------------------------------------------------
>
>                 Key: HADOOP-9495
>                 URL: https://issues.apache.org/jira/browse/HADOOP-9495
>             Project: Hadoop Common
>          Issue Type: Sub-task
>          Components: fs
>    Affects Versions: 1.2.0, 3.0.0
>            Reporter: Steve Loughran
>            Assignee: Steve Loughran
>
> {{Seekable.seek()}} seems a good starting point for specifying, testing and implementing FS API compliance: one method, relatively non-ambiguous semantics, easily assessed used in the Hadoop codebase. Specify and test it first

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira