Appcelerator Blog

The Leading Resource for All Things Mobile

Titanium Mobile Intro Series: Streams

0 Flares 0 Flares ×

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 read(), write(), close(), isWritable() and 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 BufferStream.

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.

[gist id=951461]


The 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 Titanium.Filesystem.MODE_READ, Titanium.Filesytem.MODE_WRITE and Titanium.Filesytem.MODE_APPEND.


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.

[gist id=952428]


The 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 FileStream.


In this example, we use Titanium.Media.showCamera to take a photo and stream its bytes to a file.

[gist id=952659]

Additional Resources

Stream Specification:
Stream Unit Tests: stream.js

0 Flares Twitter 0 Facebook 0 Google+ 0 LinkedIn 0 Email -- 0 Flares ×


  1. Mark Burggraf

    Reading from a large file crashes the app. On the following line:

    var instream =;

    If the input file is large (in my case, several megabytes) the app will crash at this point. It appears that buffering is implemented for the output file but not the input file.

Comments are closed.

Sign up for updates!

Become a mobile leader. Take the first step to scale mobile innovation throughout your enterprise.
Get in touch
computer and tablet showing Appcelerator software
Start free, grow from there.
0 Flares Twitter 0 Facebook 0 Google+ 0 LinkedIn 0 Email -- 0 Flares ×