Developer Documentation - WheresMyBus/android GitHub Wiki

Table of Contents

How to Obtain

We have three main repositories for our project:

Back to Top

Project Structure

The Android repository contains classes for the model portion of our app in the app/src/main/java/modules directory. These classes represent the different types of data we will be using and storing. The app/src/main/java/com/wheresmybus directory contains the view portion of our app, including classes for our various screens. And classes for our controllers are located in the app/src/main/java/controllers directory.

The OneBusAway API Wrapper repository has two directories with important files, the lib directory and the spec directory. The lib directory contains the various data classes that model the information returned from the OneBusAway API. Additionally, it contains the controller that generates the requests to the OneBusAway API and returns the appropriate data objects based on the information in the response. The spec directory contains the tests for the various classes in the lib directory.

The Where's My Bus API repository has three directories of note: the app/models, app/controllers, and config directories. The app/models folder contains the classes that represent the tables in our database. For example, we will have an alert model with fields that match the columns of the alert table in the database. The app/controllers folder contains the classes that will define the various API method calls. Using the example of alerts again, we will create an alerts controller in this folder which will have methods for getting alerts, submitting alerts, deleting alerts, etc. The config folder contains various configuration files for things like the database, the web server, and the different environments (development, test, and production).

Back to Top

How to Build and Test

To build and test the software locally in a controlled environment, follow the instructions below. We will be using the UW CSE Linux VM.

Setting up the UW CSE Linux VM

  1. Follow these instructions for installing VMWare Player (Windows/Linux) or VMWare Fusion (OSX).
  2. VMWare Player (Windows/Linux) can be downloaded here for free (the url provided on the UW page is incorrect).
  3. Download and install the "Most Recent Linux VM" by following the instructions here.
  4. When the VM prompts you to update VMWare tools, select yes.
  5. Increase the available RAM to the UW CSE Linux VM image from 1GB to at least 4GB.

Installing the Android SDK in the VM

  1. In the VM, download the Android command line tools for Linux from the url: https://developer.android.com/studio/index.html#downloads located under "Get just command line tools"
  2. Unzip the tools at a location of your choice by copying the zipped files to the chosen parent directory and running the command: tar xvf [ZIPPED_FILENAME], make note of the path to the unzipped directory called android-sdk-linux.
  3. From the directory android-sdk-linux/tools run the command android to start up the Android SDK package manager.
  4. Select the following packages:
  • From "Tools":
    • Android SDK Tools
    • Android SDK Platform-tools
    • Android SDK Build-tools (revision 25)
  • From "Android 7.0 (API 24)":
    • SDK Platform
  • From "Android 5.0.1 (API 21)":
    • SDK Platform
    • Google Play ARM EABI v7a System Image
  • From "Extras":
    • Android Support Repository
    • Google Repository
    • Google Play Services
  1. Click 'Install packages', accept all licenses and click 'Install', allow several minutes for the process to complete.

Building and Running the Android App

  1. From the android repository (https://github.com/WheresMyBus/android), build the app by executing sudo build.sh [ABSOLUTE_PATH_TO_ANDROID_SDK], for example: sudo build.sh /home/nbissiri/android-sdk-linux the result is a file called app-debug in app/build/outputs/apk
  2. Run the Android emulator by executing run_emulator.sh [ABSOLUTE_PATH_TO_ANDROID_SDK]. Hit 'enter' when asked if you want to use custom hardware settings.
  3. In another terminal, install the app onto the running emulator by executing install_apk.sh [ABSOLUTE_PATH_TO_ANDROID_SDK]. Allow the emulator a few minutes to start up before executing this command.

NOTE: Running the app from the virtual machine will not allow you to access the map feature. This is because there are no emulator devices that can run on the Linux VM that fully support the google maps API. The best way to run and test the app is from Android Studio with an emulator device using version 21 of Android with google play enabled. To test the maps feature in Android Studio follow the instructions below.

Building and Running the Android App from Android Studio

  1. Download and install Android Studio if you haven't already.
  2. Clone this repository and open the project.
  3. Follow this link
  4. Click 'Library' from the left and then Google Maps Android API from the center.
  5. Click 'Enable' at the top.
  6. Click credentials from the left, then Create credentials. Select API key.
  7. Copy the generated key and paste into the file app/res/values/google_maps_api.xml from within Android Studio
  8. Save the file, and install any dependencies detected by Android Studio before running the app with the play button in the top menu.

Running Android Tests

  1. Run the Android emulator by executing run_emulator.sh [ABSOLUTE_PATH_TO_ANDROID_SDK]
  2. In another terminal, run sudo run_tests.sh [ABSOLUTE_PATH_TO_ANDROID_SDK], this will test building, connecting to the emulator, and will run our unit tests.

Installing Dependencies for Ruby

  1. Install the necessary software by executing sudo install_ruby.sh in the api repository.
  2. Execute source /etc/profile.d/rvm.sh to enable the rvm command.

Before Running or Testing with Ruby

Add heroku to your PATH by executing PATH=/usr/local/heroku/bin:$PATH

Building and Running the API

Ruby scripts are converted into binary files at runtime, so no build step is necessary. From the api repository (https://github.com/WheresMyBus/api) run the Rails server by executing the command heroku local.

Testing the API and onebusaway Libraries

To run either test suite, execute the command rake from the corresponding repositories.

Back to Top

How to Set Up an Automated Build/Test

We will be using Travis CI for continuous integration testing of our project. Developers wishing to mimic our tests with Travis should be able to do so by having the same .travis.yml files found in our project directories in the same place in theirs and enabling their directories within Travis. This is as simple as opening an account on travis-ci.org, syncing it with GitHub, and checking the copied directory on your profile. If you do this, please change or delete the notifications section of those .travis.yml files first so that we do not get emailed. An explanation of how to configure those notifications yourself can be found here.

The automated daily build and test will be done on Travis using cron jobs. A description of how to set this up can be found here.

Back to Top

How to Release

We will use GitHub Releases for releasing new versions of our software. Steps to make a release are here. GitHub Releases includes adding compiled binaries along with an .apk file and documentation. Our releases so far are here. We will also include the release in our website and use Travis to test each release with our test client.

Back to Top

Bug Tracking

Our list of outstanding and resolved bugs can be found here.

Back to Top

Design Patterns:

Our design above uses the following software design patterns: We are using a Model-View-Controller design strategy to build our app as a whole. See UML Class Diagram: View: AlertDisplay, AlertCreate, HomeScreen, MapScreen, CatalogScreen Controllers: OBAController, WMBController Model: Bus, BusStop, Alert, Route, Neighborhood, RouteAlert, NeighborhoodAlert, Comment

We will use the Singleton design for both our controllers, as it would not make sense to make multiple. See source code: OBAController.java, WMDController.java

Many of the classes of our Model are Wrappers, most notably a Route, which just wraps an int and String. See source code: Route.java, Comment.java

Back to Top

Unit Test Coverage:

Android Studio runs IntelliJ IDEA, which has documentation about how to run tests with coverage here: https://www.jetbrains.com/help/idea/2016.1/code-coverage.html

Feature Complete Release statistics for unit tests:

Coverage

Note: Coverage numbers are slightly lower in Alert, Comment, RouteAlert, and Neighborhood Alert because they contain methods that transmit data to the server via upvote(), downvote(), getComments(), and unvote(), and are not tested in these unit tests

Back End Test Coverage:

For the api resository

For the onebusaway repository