Quick Start for Processing

WARNING: Coping this example code directly into Processing will not return any results. You must go to the Amazon Web Services site and get a developer key, and use it in step 5.

1. Get the latest version from the download page and install it.
2. Make a project and import the library.

(I recommend that you do not use Sketch > Import Library > switchboard because it will import many libraries that you do not need)

import org.switchboard.*;
 
void setup() {
}

3. Set up the listener

The resultReceived() method is called whenever a result is received, just as mouseClicked() is called whenever the user clicks the mouse. So you can think of the Switchboard as another user, giving you information when you ask for it, but in an asynchronous way.

import org.switchboard.*;
 
void setup() {
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
}

4. Create a Switchboard

First declare a Switchboard object outside of the setup() method. Then, inside setup(), create the Switchboard and pass it a reference to your processing app, this.

import org.switchboard.*;
 
Switchboard board;
 
void setup() {
	// The switchboard will be our interface to all of the services.
	board = new Switchboard(this);
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
}

5. Set any necessary keys

Many services in Switchboard require developer keys. Getting these keys is usually a very easy process. If they are required but not set, you will get an error that will tell you where to go to get the key. For this particular example, we are using the Amazon service, so we need an Amazon key, which you can get at the AWS website.

Again, if you don't replace the 'XXXXXXXXXXX' with a valid key, this example code will not work.

import org.switchboard.*;
 
Switchboard board;
 
void setup() {
	// The switchboard will be our interface to all of the services.
	board = new Switchboard(this);
	
	// Some services require developer keys
	// Try running a query without setting the key to find out where to get one
	board.setAmazonKey("XXXXXXXXXXXXXXXX");
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
}

6. Start a query

import org.switchboard.*;
 
Switchboard board;
 
void setup() {
	// The switchboard will be our interface to all of the services.
	board = new Switchboard(this);
	
	// Some services require developer keys
	// Try running a query without setting the key to find out where to get one
	board.setAmazonKey("XXXXXXXXXXXXXXXX");
	
	
	// The Amazon search takes keywords, and the index to search
	board.amazon("Music", "Manilow");
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
}

7. Catch the results

When a result is received, it will be placed into the switchboard so that you can retrieve it. Just like mouseX and mouseY contain the coordinates of the mouse click when used inside mouseClicked(), board.amazon, board.yahoo, board.google, etc., will contain the results of your query inside resultReceived(). The result will generally be located in board.[service name], where board.[service name]() is the service that you called. Each result has a different set of "getters", which are documented in the documentation page.

import org.switchboard.*;
 
Switchboard board;
 
void setup() {
  // The switchboard will be our interface to all of the services.
  board = new Switchboard(this);
 
  // Some services require developer keys
  // Try running a query without setting the key to find out where to get one
  board.setAmazonKey("XXXXXXXXXXXXXXXXXXXXX");
 
 
  // The Amazon search takes keywords, and the index to search
  board.amazon("Music", "Manilow");
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
 
  // print out the title of the result
  println(board.amazon.getProductName());
}

Running this program will produce the following output:

Manilow Sings Sinatra
The Greatest Songs of the Fifties
Ultimate Manilow
The Essential Barry Manilow
"Barry Manilow - Greatest Hits, Vol. 1"
"Barry Manilow - Greatest Hits, Vol. 2"
2:00 AM Paradise Café

8. Do something a little more interesting

Rather than just printing out the titles, now we will collect the album covers of the Amazon items that matched our query. Check out the "getters" on the documentation page again to see all of the different information contained inside an amazon() service response.

As the results are returned, we will add the images to a list, and then use the Processing image() function to draw them to the screen.

import org.switchboard.*;
 
Switchboard board;
ArrayList images = new ArrayList();
 
void setup() {
 
  size(300, 300);
  framerate(10);
 
  // The switchboard will be our interface to all of the services.
  board = new Switchboard(this);
 
  // Some services require developer keys
  // Try running a query without setting the key to find out where to get one
  board.setAmazonKey("XXXXXXXXXXXXXXXXXXXXX");
 
 
  // The Amazon search takes keywords, and the index to search
  board.amazon("Music", "Manilow");
}
 
// this method will be called whenever we get a result from any of our services.
void resultReceived() {
  
  // Instead of just printing the titles, catch the album cover
  PImage img = loadImage(board.amazon.getImageUrlSmall());
  images.add(img);
}
 
 
void draw() {
  // Loop through all of the images we have collected and draw them.
  for(int i=0; i<images.size(); i++) {
    image((PImage)images.get(i), random(width), random(height));
  }
}

Due to a bug in Processing, this applet, and any that try to load an image from a URL will not run on Windows machines in a web browser. But please download the example to see it run.

9. Now suppose you want to get images from two places

You can use as many sources as you want in one applet. But inside resultReceived(), you need to figure out what kind of result you got so that you know how to get at the information inside. To do this we first gather the "service constants" of the services that we have used. These can be found in the documentation for the methods. In this case, we have Switchboard.AMAZON and Switchboard.YAHOOIMAGE.

As you can see in the code, inside resultReceived(), we are comparing these service constants to board.resultService. This is a special variable inside the Switchboard that always contains the service constant of the service that returned the result.

So, if(board.resultService == Switchboard.AMAZON), we know that the Switchboard has just returned a result from Amazon and we can use the board.amazon getters. However, if if(board.resultService == Switchboard.YAHOOIMAGE), we must use the board.yahooImage getterd, which can be found in the yahooImage() documentation.

import org.switchboard.*;
 
Switchboard board;
ArrayList images = new ArrayList();
 
void setup() {
  size(300, 300);
  framerate(10);
 
  // The switchboard will be our interface to all of the services.
  board = new Switchboard(this);
 
  // Some services require developer keys
  // Try running a query without setting the key to find out where to get one
  board.setAmazonKey("XXXXXXXXXXXXXXXXXXXXX");
  board.setYahooKey("XXXXXXX");
 
  // Here we are starting two services
  board.amazon("Music", "Manilow");
  board.yahooImage("big bird");
}
 
// Since we called both amazon and YahooImages, board.serviceClass is either
// going to be Amazon.class or YahooImages.class.  
void resultReceived() {
 
  if(board.resultService == Switchboard.AMAZON) {
    // to get the image URL out of board.amazon, 
    // the method is called getSmallImage()
    PImage img = loadImage(board.amazon.getImageUrlSmall());
    images.add(img);
  }
  
  if(board.resultService == Switchboard.YAHOOIMAGE) {
    // to get the image URL out of board.yahooImages, 
    // the method is called getUrl()
    PImage img = loadImage(board.yahooImage.getUrl());
    images.add(img);
  }
}
 
void draw() {
  // Loop through all of the images we have collected and draw them.
  for(int i=0; i<images.size(); i++) {
    image((PImage)images.get(i), random(width), random(height));
  }
}

Switchboard is an open source project by Jeff Crouse. It is part of a study of real-time art.