[
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
