Skip to content
This repository has been archived by the owner on May 27, 2024. It is now read-only.

Home

Jump to bottom
Sean Barbeau edited this page Jun 25, 2015 · 32 revisions

Overview

The classes in this project provide support for interacting with the SIRI v 1.3 api for real-time transit data, in the form of Plain Old Java Objects (POJOSs), primarily created for use on the Android platform. Android doesn't support XML annotations such as those used in JAXB, and therefore for binding JSON or XML data to Siri Java objects POJOs are required (see this page for details).

All source code for this project is licensed under Apache 2.0.

Where are these classes used?

This library is used in the SiriRestClient mobile app, which is an open-source reference implementation Android app for interacting with the SIRI RESTful APIs (such as the Metropolitan Transportation Authority (MTA) Bus Time API, based on the OneBusAway open-source project) to retrieve real-time transit data on Android devices.

This library can be used by any Android app that wants to interact with a RESTful SIRI API to retrieve real-time transit data.

How do I use these classes?

These classes are available via Maven from the CUTR Maven Repository. Please add the below to your pom.xml to add this project to your dependencies:

<!-- SIRI POJOs -->
<dependencies>
    <dependency>
        <artifactId>onebusaway-siri-api-v13-pojos</artifactId>            
        <groupId>edu.usf.cutr.siri</groupId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

<!-- CUTR onebusaway-siri-api-v13-pojos RELEASES repository -->
<repositories>          
    <repository>
        <id>cutr-releases</id>
        <url>https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/releases</url>
    </repository>  
</repositories>

If you're using Gradle, your build.gradle would look something like this:

buildscript {
	repositories {
		mavenCentral()
	}
	dependencies {
		classpath 'com.android.tools.build:gradle:0.9.+'
	}
}
apply plugin: 'android'

repositories {
	mavenCentral()
	maven {
		// CUTR SNAPSHOTs
		url "https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/snapshots"
	}
	maven {
		// CUTR Releases
		url "https://github.com/CUTR-at-USF/cutr-mvn-repo/raw/master/releases"
	}
}

android {
	compileSdkVersion 19
	buildToolsVersion "19.0.1"
	...
}

dependencies {
	...
	// Normal Jackson libraries
	compile 'com.fasterxml.jackson.core:jackson-core:2.1.2'
	compile 'com.fasterxml.jackson.core:jackson-annotations:2.1.2'
	compile 'com.fasterxml.jackson.core:jackson-databind:2.1.2'
	// Repackaged XML-specific libraries
	compile 'edu.usf.cutr.android.xml:jackson-dataformat-xml-android:2.1.2'
	compile 'edu.usf.cutr.android.xml:stax2-api-android:3.1.1'
	compile 'edu.usf.cutr.android.xml:stax-api-android:1.0-2'
	compile 'edu.usf.cutr.android.xml:aalto-xml-android:0.9.8'
	...       
}

How were these classes generated?

There are two strategies for creating new SIRI POJOs needed for data binding:

  1. Use tools such as [json gen] (http://jsongen.byingtondesign.com/) to generate POJOs based on SIRI JSON data

  2. Strip the XML annotations and other characteristics that are incompatible with Android from the SIRI JAXB classes to create true POJOs that work on Android.

When we created these classes, for Option #1 json gen tool didn't seem to be working correctly, so we opted for Option #2 Manual Conversion.

High level summary

See this StackOverFlow post for a high-level summary of the process for Option #2. It also includes a link to how Option #2 can be automated.

Details

For Option #2, here are the steps used to manually create SIRI POJOs based on a new SIRI spec version:

  1. Generate a new set of JAXB classes from the SIRI XSD schemas (such as the current SIRI JAXB classes that exist for v1.3).
  2. Remove all XML annotations and javax.xml.* imports from all classes. The classes should compile in an Android project, so this is a good test to make sure that all incompatible XML annotations are removed.
  3. You'll need to add the classes DatatypeConstants, Duration, and XMLConstants in a new package uk.org.siri.xml.datatype. These can be copied from the same package in the SIRI v1.3 POJOs. In the SIRI objects that depend on these XML classes, you'll need to add imports to these classes.
  4. In all Enumerations, fromValue() and value() methods were replaced with fromString() and toString() methods, respectively. See the bottom of this class for an example implementation of the fromString() and toString() methods.
  5. For all classes that have the following format for a getter:
public List<AffectedStopPoint> getAffectedStopPoint() {
			if (affectedStopPoint == null) {
				affectedStopPoint = new ArrayList<AffectedStopPoint>();
			}
			return this.affectedStopPoint;
		}

... these methods were deleted and the normal getter/setter auto-generated methods from Ecilpse were inserted:

public List<AffectedStopPoint> getAffectedStopPoint() {
			return affectedStopPoint;
		}
		
		public void setAffectedStopPoint(
				List<AffectedStopPoint> affectedStopPoint) {
			this.affectedStopPoint = affectedStopPoint;
		}
  1. NaturalLanguageString and DefaultedText should be modified to include new constructor and toString methods (as shown in the above links) so that they can be constructed from single Strings for JSON parsing. This is important because the XML for fields PtSituationElement.Summary and PtSituationElement.Description includes a xml:lang attribute:
<Summary xml:lang="EN">b/d 1:00pm until f/n. local and express buses run w/delays &amp; detours. POTUS visit in MANH. Allow additional travel time Details at www.mta.info</Summary>

where the JSON looks like a single string:

“Summary” : ”b/d 1:00pm until f/n. local and express buses run w/delays & detours. POTUS visit in MANH. Allow additional travel time Details at www.mta.info”

If other XML definitions for other variables include the xml:lang field, these variables must also remain of type NaturalLanguageString.

  1. All variables with NaturalLanguageString object types were changed to String datatypes, with the exception of PtSituationElement.Summary and PtSituationElement.Description (see #6 above). This can only happen for variables whose XML elements don't contain the xml:lang field.

It should be noted that enough of the SIRI v1.3 JAXB classes were converted to POJOs in this project so they worked properly with the MTA Bus Time API in Sept. 2012. However, since MTA Bus Time doesn't implement the complete SIRI spec, there may still be some classes in this POJO project that require some modifications to work fully with Jackson data binding. To see what classes are confirmed to work with Jackson data binding on Android, see the SiriUtils code in the SiriRestClient project that loops through and prints out info retrieved from the MTA Bus Time API.

Why was this project created?

See the SiriRestClient Android app "JSON and XML Parsing Dependencies" wiki page for a lengthy discussion of why this project was created.

CUTR Release Process

We've set up a repository to hold the artifacts from this project as a Gihub project - cutr-mvn-repo.

At CUTR, we should run the following at the command-line to create a new artifact:

mvn -DaltDeploymentRepository=cutr-snapshots::default::file:"/Git Projects/cutr-mvn-repo/snapshots" clean deploy

Then commit using Git and push new artifacts to Github.

Note that the "snapshots" in the command-line should be replaced with "releases" for release versions.

Clone this wiki locally