Skip to end of metadata
Go to start of metadata
Contents

Overview

Titanium mobile needs support for stream IO operations on appropriate objects such as files, sockets and any other types we decide upon in the future.  In order to support generic stream handling and the exchange of data between streams a common stream interface needs to be defined.

This document will outline the proposed additions for supporting stream operations within Titanium mobile, types that will support stream operations, API changes and source examples.

Icon

A separate spec exists that outlines encoding support for numeric and string values.  The Encoding Spec enables the addition of reading and writing of numeric and string values along with support for specific encoding. In the future, we plan to support the ability for a developer to define their own stream types that can be used alongside the native Titanium streams.

Justification

Currently there isn't an easy or generic manner for reading or writing data from one complex type like xxx to another.  By providing a Stream interface that these complex types can implement, we can allow developers to simplify the process of moving data between these complex types.  In addition to the core stream interface which just allows these types to interact in a generic manner, convenience functions would be provided in a new Stream module that would allow many of the common operations on streams to be simplified further (IE:  writing all data from one stream to another).

Ultimately, adding Stream support will enable our developers to simplify their source code and make IO operations for streaming types much more approachable.

Definitions

  • Stream - Generic input / output object that can be used for read / write operations with a variable frequency and amount.
  • Buffer - Generally represents temporary storage for data when moving from one location to another (such as reading data off a socket and then writing to a file).  In our case, the buffer will be a container for binary data rather than being limited to only string data. Buffer Spec

Proposed Tasks

  • Create Stream interface
  • Create BufferStream object that implements Stream interface
  • Create BlobStream object that implements the Stream interface
  • Create FileStream object that implements Stream interface
  • Update Socket object to implement Stream interface

Proposed API

Stream objects below only list the methods that are applicable to the IO operations.  More methods may exist already that are left out for the sake of focus on the stream operations.

Ti.Stream

Module

Stream module would expose generic Stream functionality outside of just the types that implement the Stream interface.

Properties:

Methods:

Interface

Common interface defines which methods all stream objects will need to support.

Methods:

FileStream

File stream object used for IO operations on a physical file.  Implements TiStream interface (not listing interface methods).

Creating file stream object:

Socket

Socket object that supports IO operations.  Implements Stream interface (not listing interface methods).

* refer to sockets spec for details on creating a socket

Methods:

Source examples

Reading data from file:

Reading data from file using readAll:

Writing data from one file to another

Write data from one stream to another.  Useful for when writing large amounts of data that can not or should not be read into memory as a single chunk.

Reading data from one stream into a handler method:

Writing data from a buffer into a file (process is exactly the same if you replace TiBuffer with TiBlob):

2 Comments

  1. There may be a valuable use case for assigning identifiers to read/write operations so that a user can know when specific ones complete (i.e. they queue up X number of writes, and display a progress bar that updates as each one completes). To support this I suggest we add a an int ID parameter to each asynch read and write method.

  2. Although the spec states that there will be a second spec dealing with encoding of variables to buffers (i.e. string encoding) we will need stopgap measures for being able to test systems like sockets (see TCP Socket API Spec). To this end in the socket spec the following method is proposed:

    Ti.Buffer Ti.createBuffer({data:string}) : Creates a buffer with a data representation of the provided string (considered to be UTF8). NOTE: this is meant to be a stopgap until there is an I/O Stream spec dealing with string encoding into buffers.

    This method would be made available throughout prerelease 1.7.0 in order to give us the capability to test certain buffer and I/O stream features, and be removed/replaced once a complete string encoding spec was approved and implemented.