Algorithms and OOD (CSC 207 2014F) : Labs

Laboratory: A Simple Ushahidi API


Summary: In today's laboratory, you will you will build a variety of small programs that let you think about data representation, APIs, and output, using the Ushahidi crowd mapping framework as your data source. You will explore a variety of issues related to Java programming. You will learn how to import external libraries into your Eclipse projects. And you will have the joy of dealing with incompletely documented and implemented code.

Introduction

In this exercises, we will be working with the Ushahidi crowdsourcing platform, http://www.ushahidi.com/. In particular, we will be grabbing data from simulated and real Ushahidi installations.

To interact with Ushahidi, we will be using a simple API designed and implemented by Grinnell students and faculty.

This lab asks you to learn more about Ushahidi and that API. As you learn more (and write programs that express your learning), you will be developing a variety of skills in developing software and thinking from an object-oriented perspective.

Preliminaries

a. In a recent exercises, you designed your own model for working with Ushahidi. Quickliy refresh your memory about your design.

b. Look at the Java documentation for the simple Ushahidi API, available at http://www.cs.grinnell.edu/~rebelsky/Glimmer/Ushahidi/docs/. Focus on

  • the constants and methods in UshahidiIncident, which represents incidents;
  • the constants and methods in UshahidiLocation, which represents locations;
  • the methods in UshahidiClient and UshahidiAdmin, which provide client and administrative access to an Ushahidi installation; and
  • the constants and methods in UshahidiUtils, which provides some utility methods for incidents.

You will note that we did not tell you to look at the fields. As a client of these classes, you should not care what the fields are.

c. After examining the documentation, You may find it helpful to note what methods you expected to find but did not find (or that you included in your design but did not see in yours), and what methods you found that you did not expect to find (or that you did not include in your design but see here). If there are methods that you think would be helpful, you might want to let me know. I may add them or I may explain why they aren't there.

Preparation

a. Create a new Eclipse project for this exercises. You can name the project whatever you like, provided it's not in bad taste.

b. Make a copy simple-ushahidi-api.jar, the JAR file for the simple Ushahidi API, available at http://www.cs.grinnell.edu/~rebelsky/Glimmer/Ushahidi/code/simple-ushahidi-api.jar. A JAR is a Java Archive, a standard way to group compiled Java code for use in other projects.

c. The Ushahidi API relies on JSON. (You can look it up.) Make a copy of the JAR file for JSON, available at http://www.cs.grinnell.edu/~rebelsky/Glimmer/Ushahidi/code/json.jar.

d. Import those JARs into your project using the instructions available at http://www.wikihow.com/Add-JARs-to-Project-Build-Paths-in-Eclipse-(Java). (If you find and follow other instructions, that's fine.)

Assignment

Exercise 1: Printing Incidents

1. Create a new utility class, UshahidiExtensions.java, that has one static method, printIncident, that takes as input a PrintWriter and an UshahidiIncident and prints the incident out using a format something like the following (things in all caps should be replaced by the corresponding value).

Incident #: TITLE
  DESCRIPTION
  Location: LOCATION
  Status: (MODE, ACTIVE, VERIFIED)

2. Create a new main class, PrintIncidentExperiment.java, with the following method. Note that you'll need to fill in the details of myIncident before the code runs.

    public static void main(String[] args) 
      throws Exception
    {
      // Create the output device
      PrintWriter pen = new PrintWriter(System.out, true);

      // A few basic incidents
      UshahidiExtensions.printIncident(pen, UshahidiUtils.SAMPLE_INCIDENT);
      UshahidiExtensions.printIncident(pen, UshahidiUtils.randomIncident());
      UshahidiExtensions.printIncident(pen, UshahidiUtils.randomIncident());

      // A newly created incident
      UshahidiIncident myIncident = new UshahidiIncident(...);
      UshahidiExtensions.printIncident(pen, myIncident);

      // One from a list
      UshahidiClient client = UshahidiUtils.SAMPLE_CLIENT;
      UshahidiExtensions.printIncident(pen, client.nextIncident());

      // One that requires connecting to the server
      UshahidiClient webclient = new UshahidiWebClient(URL);
      UshahidiExtensions.printIncident(pen, webclient.nextIncident());
    } // main(String[])

Exercise 2: Incident Lists

While we will generally be working with incidents taken from a server, it can be helpful for testing to build our own incident list. Write a method that creates an UshahidiTestingClient of about a dozen incidents that you can use for experiments. You should try different dates, different locations, and so on and so forth.

Exercise 3: Extreme Incidents

a. Write a method that, given an UshahidiClient, prints out the incidents with the lowest and highest id. You can use only nextIncident and hasMoreIncidents.

b. Try your method with the custom incident list you created in a previous problem.

Exercise 4: Web Incidents

In the previous examples, you've been working with a simulated Ushahidi installation. Now let's try working with a real one.

a. Write program that creates an UshahidiWebClient that connects to http://ushahidi1.grinnell.edu/sandbox and prints out the first incident returned by nextIncident.

b. Manually add a new incident to that server (using the Web interface or the phone app). Then rerun the program from the previous step. What if anything, do you observe?

c. Run your lowest/highest id method from a previous exercise using an UshahidiWebClient that connects to the sandbox.

For Those With Extra Time

Extra 1: Identifying Incidents

a. Write a method that, given an UshahidiClient, a start date, and an end date, prints all incidents that happen between the two dates (in any order). You can use only nextIncident and hasMoreIncidents.

b. Check your method using the testing client.

c. Check your method using the web client.

Extra 2: Selecting Incidents

a. Write a method that, given an UshahidiClient, a start date, and an end date, builds and returns an array or vector of all the incidents that fall between those two dates. (In solving this problem, you may find it useful to grab the array of all incidents.)

b. Write a method that, given a vector of incidents, a latitude, a longitude, and a distance, creates a new vector of all the incidents that fall within that distance of the location.

Citations

The Simple Ushahidi API was originally written by Daniel Torres. The overall design of the current API is due to Samuel A. Rebelsky, but much of the underlying code draws upon Mr. Torres' work.

This laboratory is based on a longer assignment that was given in the Fall 2013 section of CSC 207.