Re: File API to separate reading from files

I want to clarify that it is indeed possible to adjust my proposal to  
sidestep the issue of dealing with bytes directly. Here's how.

Remove the read() method in the InputStream interface.
Remove the DataHandler interface

Notice that composability doesn't depend on the availability of raw  
bytes to the JavaScript interface. In fact, the implementation should  
be able to dissect the bytes corresponding to the input stream being  
passed so that it can either:

1. produce a data URL
2. produce text blocks
3. produce binary string blocks

I hope that eliminates any expectation of a dependency on representing  
bytes as integers from my proposal. I just threw it in since I felt  
Gears thought it was OK. Perhaps, a real byte handler can be added  
when ECMAScript is ready with byte arrays and the File I/O will serve  
as a rallying cause for it.

Nikunj

On Aug 19, 2009, at 11:47 AM, Nikunj R. Mehta wrote:

> Here's an alternative, more easily extensible, proposal for reading  
> files. It provides applications a way to read small amounts of data  
> at a time. It also allows applications to concurrently read the same  
> file.
>
> Firstly, there is a simple interface to access file metadata. This  
> metadata is always accessed synchronously. A file object could be  
> passed to XHR, in which case it can upload the file during the  
> send() process.
>
> interface File {
>   readonly attribute DOMString name;
>   readonly attribute DOMString mediaType;
>   readonly atribute DOMString url;
>   readonly attribute unsigned long long size;
> }
>
> Secondly, a list of files can be obtained using some UI.
>
> typedef sequence<File> FileList;
>
> Thirdly, an abstract interface is an input stream that is not  
> limited to files. It works at the level of bytes that files are made  
> of. The read() operation can specify the extent that is required. If  
> an application wishes to read small increments, it can thus specify  
> those increments. Of course, the File interface identifies its size,  
> so the application can suitably choose increments. Processing of  
> blocks read from the file occurs in callbacks. XHR could also  
> consider taking an InputStream parameter during the send() operation.
>
> interface InputStream {
>   read(in DataHandler, [optional in] long long offset, [optional in]  
> long long length);	
>   abort();
>   attribute Function onerror;
> }
>
> Fourthly, reading a block of bytes is supported through an interface  
> that accepts an array of integers. This is similar to the Gears Blob  
> interface.
>
> [CallBack=FunctionOnly]
> interface DataHandler {
>   handle(in sequence<int> data);
> }
>
> Fifthly, a file can be used for reading an input stream by  
> specifying the name of a file when constructing the stream
> [Constructor(in File toOpen)]
> interface FileInputStream : InputStream {
> }
>
> Sixthly, one can create various kinds of derived readers such as  
> text reader, binary string reader, and data URL reader. By  
> inheriting from InputStream, the basic mechanisms such as abort and  
> onerror are inherited. Moreover, the base read behavior is altered  
> by the subclass although it behaves in a similar manner, except that  
> the data seen outside is different.
>
> [Constructor(in InputStream base)]
> interface BinaryStringInputStream : InputStream {
>   read(in StringDataHandler, [optional in] long long offset,  
> [optional in] long long length);	
> }
>
> The callback is provided a DOMString. The String's length is  
> expected to match the increment requested.
>
> [CallBack=FunctionOnly]
> interface StringDataHandler {
> 	handle(in DOMString data);
> }
>
> For text reading, encoding is optionally specified.
>
> [Constructor(in InputStream base, [optional in] DOMString encoding)]
> interface TextInputStream : InputStream {
>   read(in StringDataHandler, [optional in] long long offset,  
> [optional in] long long length);	
> }
>
>
> A file can be alternatively read as a dataURL using a similar kind  
> of handler as above.
>
> [Constructor(in InputStream base)]
> interface FileDataURL: InputStream {
>   read(in StringDataHandler, [optional in] long long offset,  
> [optional in] long long length);	
> }
>
> This API has the advantage that it can cleanly be extended to deal  
> with both writing use cases and binary data. Furthermore, it can  
> also support extensions that perform cryptographic, compression, or  
> coding on top of the basic interfaces.
>
> To compare with the editor's draft, here's a typical programming  
> case in JavaScript:
>
> var fileList = ...
> // There is a mistake in the example provided in Section 3 where it  
> does fileList.files[0]
> var myFile = fileList[0];
>
> // *According to editor's draft*
> myFile.getAsText(handleDataAsText)
> function handleDataAsText(fileContent, error) {
>   if (error) {
>
>   }
> }
>
> // *According to my proposal*
> var stream = new TextInputStream(new FileInputStream(myFile),  
> "UTF-16");
> stream.read(handleDataAsText);
> stream.onerror = errorHandler;
> function handleDataAsText(fileContent) {
>
> }
>
> function errorHandler(error) {
>
> }
>
> Note the two differences:
> 1. Error handling is separated from file reading
> 2. Two extra objects are needed to read text data out of the file.  
> However, the composability of input streams enables a far richer  
> library to operate.
>
> This API matches more closely the Java API for IO. It also benefits  
> from the extensibility model used in Java, while retaining the  
> asynchronous processing nature that is preferred in ECMAScript  
> environments. It is also not too different from the editor's draft  
> in that it does not introduce a completely different kind of data  
> processing - we are still looking at callbacks. However, the  
> improvement is in the composability of streams as well as supporting  
> multiple concurrent file readers and processing blocks of data at a  
> time.
>
> Progress events can be built on top but I welcome suggestions to  
> build them in to this proposal.
>
> Nikunj
> http://o-micron.blogspot.com
>
>
>

Nikunj
http://o-micron.blogspot.com