Welcome to the second part of our series introducing some of the new features coming up in Titanium Mobile 1.7.0. This second installment concerns Streams and is therefore intimately related to the subjects of the first installment, Buffers and Codecs. Like the first installment, this article is introductory in scope and ends with links to additional resources containing more comprehensive information about these new APIs.
Types of Streams
A stream is a data type used to serially read and write bytes. The term “Stream”, used generically, refers to a data type which implements a particular interface consisting of the methods that you would expect from a stream-like object, namely
isReadable(). The Titanium Mobile SDK, starting with version 1.7.0, defines four types which implement this interface:
Titanium.Stream.BufferStream, an in-memory stream implementation.
Titanium.Stream.BlobStream, a read-only stream specifically for reading from Titanium Blobs.
Titanium.Filesystem.FileStream, for reading and writing files on the mobile device.
Titanium.Network.Socket.TCP, a TCP socket implementation which, among other things, implements the Stream interface. Sockets, of course, have lots of other interesting features beyond their stream implementation, and therefore there will be another installment of this article series devoted to sockets. We won’t cover sockets any further in this article.
We introduced Buffers in the first installment of the series. They are basically resizable byte arrays. A
BufferStream reads or writes the bytes in a
Buffer in a serial fashion and maintains an internal pointer to the current read/write position in the
Buffer. So rather than needing to read or write each individual byte in a
Buffer, you can read or write a series of bytes using a
One use-case might be if you want to prepare a message in its entirety before opening a socket and sending the message. You can use a
BufferStream to assemble the message in a buffer in memory, then later pass that buffer to a socket write operation.
Here’s a simple example of writing strings to a
BufferStream and then reading them back.
FileStream, surprise surprise, helps you read from and write to files on the mobile device. This can have memory advantages, such as if you want to read and write in chunks rather than pull a file’s entire contents into memory at one time.
There are two ways to get a
FileStream instance. If you already have a
File object, you can open a stream for it by using the new
open([mode]) method of
Titanium.Filesystem.File. Alternatively, you can skip getting the
File object if you have no other use for it and instead get a stream directly with the new
Titanium.Filesystem.openStream([mode], [path]) method.
The supported modes are
This simple example reads and writes a file in 1K chunks rather than loading up the entirety of the file in memory. In this example we get streams by first getting
File objects then calling their
open() methods. However, in the case of the output file, we show the alternative
openStream(...) method as well in a commented line.
BlobStream is a read-only stream that provides you with the ability to read blobs in chunks rather than load them up completely in memory. Blobs appear in a few places throughout the Titanium API, such as in Titanium.Media when dealing with images from the camera and photo gallery. You read from a
BlobStream in the same manner you would for a
BufferStream or a
In this example, we use Titanium.Media.showCamera to take a photo and stream its bytes to a file.
Stream Specification: http://wiki.appcelerator.org/display/guides/Stream+Spec
Stream Unit Tests: stream.js