IBM Streams Introductory Hands-On Lab

For use with the Streams Quick Start Edition VMware Image (QSE VM), Version 4.1.

Getting started with IBM Streams

This is an introductory-level lab and the best way to learn the basics of Streams application programming.

Lab instructions

The instructions for this lab are in PDF format. This allows you to download the instructions, print them if you like, and work on the lab offline.

Download PDF (4 MB)

Lab installation

Beginning with version 4.0.1, the QSE VM does not come with the lab preinstalled, so you have to install it yourself. The rest of this page covers the details.

Download Installation Package (4 MB)

These instructions guide you through the installation of all required components of the Introductory Lab for Streams 4.1. They assume you are using the QSE VM, but with minor adjustments for differences in environment they can can be used for any system with a Streams 4.1 installation.

The essence of this process is:

  1. Download the installation package (IntroLab_4.1.zip; see button above)
  2. Extract the contents of the installation zip file
  3. Run the installation script (IntroLab_4.1_Install.sh)

The script takes care of everything, automatically. It does not matter which directory contains the script, nor what your present working directory is when you run it.

For advanced Linux users

The detailed instructions below are intended for users who are unfamiliar with Linux and command shells; they avoid the command line altogether. If you are proficient in Linux and the bash shell, you should have no problem mapping these to an equivalent command sequence, if you prefer.

  1. If you got to this page from another environment, open it from within the QSE VM. (Naturally, this assumes that you have internet access from within VMware.)
  2. Click the Download Installation Package (4 MB) button at the top of this section. By default, Firefox will open the package with the Archive Manager; to let it go ahead, click OK in the Opening IntroLab_4.1.zip dialog.
  3. In the Archive Manager, click Extract extract in the tool bar.
    • In the Extract dialog, accept all defaults and click Extract to put the files in the streamsadmin home folder.
    • In the Extracting files from archive dialog, click Show the Files to open a File Browser showing the extracted files in that folder.
    • Close the Archive Manager.
  4. Double-click on the IntroLab_4.1_Install.sh shell script; in the dialog, click Run in terminal.
  5. A Terminal window opens up, displaying progress. More detailed progress messages are written to the IntroLab_4.1_Install.log file (in the same folder). Installation will take up to five minutes or so, in part depending on the speed of your internet connection; it includes building a required toolkit, which involves downloading additional components, and building all the lab projects. When the installation is complete, press any key to terminate the script and close the Terminal.

The script removes itself as well as the installation files archive, so after successful completion you only have the downloaded file, the installation log, and an uninstall script in your home folder (in addition to any files already there before you started).

The uninstall script, IntroLab_4.1_Uninstall.sh, removes all files related to this lab, including toolkits, data, and workspaces. It issues extra prompts to guard against unintentional deletion of any work you may have added to the workspaces. You may keep this script around in case you want to clean up your environment someday.

If installation fails

If for some reason installation was not successful, you will see a message to that effect; additional information may be available in the install log. The script cleans up after itself upon failure by removing any files and directories it may have already installed.

Reasons why installation may fail 1

The install script will not install over an existing /home/streamsadmin/Workspaces directory. This is to prevent overwriting any existing work. If you have existing work that you want to save, move or rename your Workspaces directory before running the install script. If there is nothing to save, simply delete the Workspaces directory and everything below it.

Reasons why installation may fail 2

If you are not using the QSE VM and do not have Apache Ant (1.8 or later) or Apache Maven (3.2 or later) installed in your environment, installation will fail. These two utilities are required to build the Internet Toolkit, which is used in the final chapter of the lab. Explaining exactly how to install these utilities is beyond the scope of this document. Other causes of failure may have to do with not being able to write files into subdirectories, such as permission problems, pre-existing files, and insufficient disk space.

Troubleshooting non-obvious failures

If the progress messages and log file provide insufficient clues as to what went wrong, and you are an experienced Linux user (or have someone like that to help you) use a Terminal window to execute the install script from the command line. Before running it, execute this command:
export DEBUG=yes
This greatly increases the information recorded in the log file and should allow you to pinpoint the problem.

Join The Discussion