Front End

The Front-end component is what the end user interacts with; it encompases all the modules necessary to answer an HTTP or SMS request.

Front end CIS

Public users interact with onebusaway-nyc using the desktop web page, mobile web page, SMS, SIRI API and DIY sign. These services are encapsulated by three modules: onebusaway-nyc-webapp, onebusaway-nyc-sms-webapp, and onebusaway-nyc-presentation. Significant packages, classes and configuration files are described below.

onebusaway-nyc-webapp

This module provides the web application that includes the desktop web page, mobile web page, and SIRI API.

Java

• org.onebusaway.nyc.webapp.actions - classes for the main entry point for the desktop web application
  • OneBusAwayNYCActionSupport - Provides general functionality needed by other actions, notably user and cache breaker information
• org.onebusaway.nyc.webapp.actions.api - classes that provide data for various mobile and desktop page calls, mostly related to searching, stop data, and configuration values
  • AutocompleteAction - Provides suggestions to the autocomplete UI for searching on the desktop and mobile web pages.
  • ConfigAction - Exposes configuration service values to the desktop and mobile web applications.
  • ReleaseAction - Provides information about the currently running version of this module.
  • SearchAction - Receives search queries from the desktop web page, sends the query to the search service and provides search results.
  • SearchResultFactoryImpl - responsible for creating results from api model classes only for actions in this package
  • StopForIdAction - Provides information about the requested stop including arrival information.
  • StopsOnRouteForDirectionAction - Provides a list of stops for a route and direction displayed on the desktop web page.
  • StopsWithinBoundsAction - Provides a list of stops to display on the desktop web page map
• org.onebusaway.nyc.webapp.actions.api.model - model classes for above API results
• org.onebusaway.nyc.webapp.actions.api.siri - action classes that expose the SIRI API, supporting XML or JSON results based on HTTP Accept header
  • StopMonitoringAction - SIRI stop monitoring interface
  • VehicleMonitoringAction - SIRI vehicle monitoring interface
• org.onebusaway.nyc.webapp.actions.m - action classes for the mobile web interface
  • ColorStylesheetAction - dynamically provides css to the mobile page for styling the left side of the stop list
  • SearchResultFactoryImpl - responsible for creating results from mobile model classes only for actions in this package
• org.onebusaway.nyc.webapp.actions.m.model - model classes for mobile search results
• org.onebusaway.nyc.webapp.actions.m.wiki
  • IndexAction - action class for providing mobile-specific XWiki content in the mobile web page
• org.onebusaway.nyc.webapp.actions.sign
  • SignAction - action class providing the DIY sign
• org.onebusaway.nyc.webapp.actions.wiki
  • IndexAction - action class for providing XWiki content in the desktop web page
• org.onebusaway.nyc.webapp.actions.wiki.model
  • NycWikiPageWrapper - a model class to represent an XWiki page in Java, used by both the mobile and desktop pages
• org.onebusaway.nyc.webapp.api - classes supporting the use of SIRI API keys
  • ApiKeyInterceptor - a Struts interceptor that validates the API key and enforces rate limits in calls to the SIRI API.
  • CreateAPIKeyOnInitAction - creates 'OBANYC' API key on context initialization if key creation is enabled by Maven profile (createAPIKey = true)

Configuration files

• application-context-webapp.xml - General Spring context for this module.
• data-sources.xml - Spring data source configuration including Transit Data Service, Config Service, database, geocoded and more
  • wktFilterPolygon - On the geocoder, the area used to filter out results returned from the geocoder, providing more precise control over results displayed to the user
  • resultBiasingBounds - On the geocoder, the bounding box sent to geocoders supporting it (Google, for example) as a suggestion of where to search geographically for results
  • defaultBounds - Default value for the bounding box of all service areas
• git.properties - Provides values displayed by ReleaseAction related to the version number and other Git attributes
• log4j-stdout.xml, log4j.xml - Log4j configuration files
• struts.xml - Struts configuration file

Web Application Files

• Config.js - Provides urls for API endpoints and some general functions for Google Analytics, map popups and map markers
• Util.js - General utility functions for dates and string hash codes
• Wiki.js - Functions to add layout and ad functionality to wiki pages
• Mobile.js - Adds autocomplete, refresh, and location based searching for mobile browsers that support it
• GoogleMapWrapper.js - A wrapper that adds configuration to the Google Map instance, providing default map bounds, zoom, subway overlay tiles, and a custom styled base map
• Popups.js - Code for creating and managing all content in the stop and vehicle map popups on the desktop site
• RouteMap.js - Code for managing the interaction with and display of data on the desktop site's map
• Sidebar.js - Code for managing the interaction with and display of data, including route information, alerts, and geocoded results, in the left column of the desktop site
• Wizard.js - Code to display and manger user interaction with the wizard interface
• decorators.xml - Struts decorators config file
• urlrewrite.xml - URL rewrite rules for QR codes, mobile, wiki, and API requests
• web.xml - Web context configuration file
  • xwikiUrl - The URL for the XWiki instance providing wiki content
  • wikiDocumentEditUrl - The URL for exiting an XWiki document, using the %{namespace} and %{documentName} parameters to generalize
  • wikiAttachmentUrl - The URL for an XWiki document attachment, using the %{namespace}, %{documentName}, and %{attachmentName} parameters to generalize

The remainder of the web application files in src/main/webapp/ are standard Struts jsp files, decorators, and css.

onebusaway-nyc-sms-webapp

This module provides the SMS web application. Normally requests to this application will come from an SMS broker that relays messages between cellular users and this application.

Java

• org.onebusaway.nyc.sms.actions
  • IndexAction - The action class that processes and replies to SMS requests.
    • MAX_SMS_CHARACTER_COUNT - The maximum number of characters to allow in a single SMS
  • SearchResultFactoryImpl - The result factory for the SMS interface, using classes in the model package below
  • SessionedIndexAction - A superclass for IndexAction that provides session functionality for user interactions spanning multiple SMS requests
• org.onebusaway.nyc.sms.actions.model - Model classes for SMS query results
• org.onebusaway.nyc.sms.impl - Utility classes for implementing SMS sessions
  • SessionManagerImpl - A custom implementation to manage the starting, updating and stopping of sessions
    • _sessionReaperFrequency - The interval at which to check for stale sessions
    • _sessionTimeout - Timeout, in seconds, at which point a session will be considered stale
  • MemcacheClientFactory - Returns a client that can read session data stored in Memcache
  • MemcacheSessionManagerImpl - Customizations to the SessionManagerImpl to read and write session data to Memcache
  • MobileCommonsSessionInterceptor - A Struts interceptor to grab information (the user's phone number) from requests from the SMS broker to use to key sessions on
• org.onebusaway.nyc.sms.services - Interfaces for implementation of SMS sessions
  • GoogleAnalyticsSessionAware - If implemented, allows the Struts action to run custom code to initialize the user's session
  • SessionManager - The SessionManager interface

Configuration files

• application-context-sms-webapp.xml - The Spring application context
• data-sources.xml - Spring data source configuration including Transit Data Service, Config Service, database, geocoded and more
  • wktFilterPolygon - On the geocoder, the area used to filter out results returned from the geocoder, providing more precise control over results displayed to the user
  • resultBiasingBounds - On the geocoder, the bounding box sent to geocoders supporting it (Google, for example) as a suggestion of where to search geographically for results
  • defaultBounds - Default value for the bounding box of all service areas
  • cacheManager.cacheManagerName - An override to replace the default cache manager to one that flushes the cache periodically
  • addresses - The address of the Memcache server to use for session data
• log4j-stdout.xml, log4j.xml - Log4j configuration files
• struts.xml - Struts configuration file

Web Application Files

• index.jspx - A simple JSP template that just prints out the plain text context of the SMS response
• exception.jspx - A simple plain text error response
• web.xml - Web context configuration file

Shared Dependencies

The following modules are shared across the front-end CIS as a maven dependency.

onebusaway-nyc-presentation

Shared classes used in both onebusaway-nyc-webapp and onebusaway-nyc-sms-webapp.

• org.onebusaway.nyc.geocoder.impl - Geocoder implementation classes
  • FilteredGeocoderBase - An abstract parent class providing polygon filtering functionality
  • BingGeocoderImpl - A geocoder implementation based on Bing's service
  • GoogleGeocoderImpl - A geocoder implementation based on Google's service
• org.onebusaway.nyc.geocoder.model - Model classes to encapsulate results from different geocoder implementations
• org.onebusaway.nyc.geocoder.service - Interfaces for geocoder implementations and model classes
• org.onebusaway.nyc.presentation.impl
  • AgencySupportLibrary - Utility functions to parse agency id strings
• org.onebusaway.nyc.presentation.service.realtime - Presentation-related service interfaces
  • PresentationService - Interface defining a service to provide information about how to display realtime bus information
  • RealtimeService - Interface defining a service to provide realtime bus information
• org.onebusaway.nyc.presentation.impl.realtime - Presentation-related service implementations
  • SiriSupport - Utility class to populate SIRI objects
• org.onebusaway.nyc.presentation.service.search - Search-related interfaces
  • SearchService - Interface defining a search service allowing search by freeform text usually related to route, stop, or location
  • SearchResultFactory - Interface defining a search result factory. Each interface, desktop, mobile and SMS, provide a custom implementation
• org.onebusaway.nyc.presentation.impl.search - Search-related interface implementations
  • SearchServiceImpl - The search service implementation used by all interfaces, desktop, mobile and SMS
  • AbstractSearchResultFactoryImpl - An abstract base class providing default implementations of service alert related methods for desktop, mobile and SMS search result factories
• org.onebusaway.nyc.presentation.impl.service_alerts - Helper classes for service alerts
  • ServiceAlertsHelper - Helper methods for adding service alert data to SIRI results
  • ServiceAlertsTestSupport - Methods to assist testing service alerts
• org.onebusaway.nyc.presentation.model - Model interfaces/classes for search results
  • SearchResult - An interface used to identify a class as a search result, since search result objects can be very different for desktop, mobile, and SMS
  • SearchResultCollection - A class encapsulating a collection of SearchResults and providing methods to modify it

Configuration files

• application-context.xml - Spring configuration that instantiates service implementations that are present in org.onebusaway.nyc.presentation.impl
• log4j-stdout.xml, log4j.xml - Log4j configuration files

OneBusAway API

The module below comprise the set of webservices that is know as the OneBusAway API.

onebusaway-nyc-api-webapp

A version of the onebusaway-api model/on-the-wire classes with the real time status information removed. For OneBusAway-NYC by convention the OneBusAway API is used for discovery of static/schedule data only, and realtime data comes from the standards-based SIRI APIs. This forked version of the model classes fulfills that vision. If other deployments would like real time data to be exported via the OneBusAway API, you can point the standard onebusaway-api-webapp to the OneBusAway NYC transit data service.

The transit data service can reference the bundle to provide:

• Current phase of bus journey (phase above)
• The trip being served (directly from above)
• The block being served (directly from above)
• The route being served (implied from trip)
• Route direction being served (implied from trip)
• Geographic path to be followed by the vehicle (implied from trip)
• Snapped current location of the bus to its route's path or street geometry (latitude/longitude from above)
• Schedule deviation (with schedule time above, calculated using data in transit graph)
• Bus stops the bus is scheduled to serve in the future, in order (with trip and distance along trip, calculated using data in transit graph)
• For each stop the bus is scheduled to serve:
• Name and geographic location of the stop (from transit graph)
• Location of the bus relative to the stop, measured in stops away and linear distance along route (with trip and distance along trip, calculated using data in transit graph)

onebusaway-nyc-transit-data-federation-webapp

The onebusaway-nyc-transit-data-federation is a collection of transit data services that are an overlay over the existing OBA core services. These are things that are imagined to be NYC specific, that may be merged into OBA core in the future depending on community appetite.

Examples:

• Bundle switching service: switches bundles when the currently loaded one expires.
• Run Service: matches trips to runs from MTA internal schedule formats (STIF).
• Destination Sign Code Service: matches trips to "DSCs", an MTA convention.
• Base Location Service: checks to see if a coordinate is within a base/depot.
• Prediction Integration Services: components that inject records into the OneBusAway Transit Data Service from an external prediction source.
• Scheduled Service Service: answers queries about available service in a given route/direction(+stop).
• NycTransitDataService: a wrapper for the OBA Transit Data Service that permits extension from within the NYC-TDF.

The onebusaway-nyc-transit-data-federation-webapp exposes all of the above via Hessian so that multiple front-end webapps (e.g. nyc-webapp and nyc-sms-webapp) can all connect to one running instance and avoid the requirement to have multiple bundles loaded into memory at once.

Display Logic

The above User Interfaces remain consistent with respect to displaying formal vs. informal bus information. This logic is described in User Interface String Display Logic

High Availability

The front-end is designed to scale linearly by adding instances as user demand increases. As such, it works nicely behind a load balancer, especially in auto-scaling situations. The SMS session state provides a slight hiccup, being the exception to the otherwise stateless APIs that make up the front-end. For this exception alone, memcahced is required to share session state across instances. Sticky-session load-balancers can reduce the need for memcached.

By ensuring a minimum of two front-end servers are always operation, high-availability is ensured.