Webapp Configuration Guide - Hillsborough-Transit-Authority/onebusaway-application-modules GitHub Wiki

The onebusaway-webapp module provides all the web-based user interfaces. That includes:

• standard web interface (including a "Sign-Mode" for large displays)
• iPhone-optimized web interface
• text-only web interface

We use the Apache Struts 2.x framework for mapping incoming web requests to Java action handlers and mapping action results for rendering the response. For the most part, we use standard JSP for generating HTML responses.

For much of the AJAX-ified tools in the standard web interface, we use the Google Web Tool, which compiles Java code into optimized javascript. See some specific notes on working with GWT below.

For a deep-dive through the OBA technology stack, check out the An Example Webpage Request page that details how a HTTP request in processed and turned into a response.

To run the OneBusAway webapp, you need to follow a couple of steps:

1. Check out the OneBusAway source from Github into Eclipse
2. Setup a Tomcat server instance in Eclipse. Be sure to add the onebusaway-webapp project to the server you setup
3. Configure appropriate data sources for the webapp
4. Start the server and check for exceptions
5. Browse to the results at http://localhost:8080/onebusaway-webapp

Checkout the Developer's Installation Guide for detailed instructions.

The webapp module won't just run out of the box. You need to configure the various data sources it will use to retrieve transit data, user data, and other configuration information.

Because this configuration information is typically specific to each developer, many of the files controlling configuration are not included in the source tree. However, check out the Developer's Installation Guide page for some sample data-sources.xml files.

The bulk of configuration is performed in the file:

onebusaway-webapp/src/main/resources/data-sources.xml

Again, by default, this file is not actually included in the source tree. We do, however, provide a default starting point in onebusaway-webapp/src/main/default-resources/data-sources.xml. Simply copy the data-sources.xml file into the src/main/resources and begin editing. We'll walk through the sections in that default file, describing what they are up to.

First, we specify out transit data source:

<bean id="transitDataService" class="org.springframework.remoting.caucho.HessianProxyFactoryBean">
  <property name="serviceUrl" value="http://soak-transit-data.onebusaway.org/puget_sound/remoting/transit-data-service" />
  <property name="serviceInterface" value="org.onebusaway.transit_data.services.TransitDataService" />
</bean>

Next, we specify a database data source that will be used by various components (user profiles, etc):

By default, we specify an in-process HSQLDB, because it's the easiest to setup. However, this convenience comes with a loss of flexibility (can't connect to the db with command-line tools, can't share the db between multiple processes), so feel free to switch the datasource to something different (a stand-alone HSQLDB instance, a MySQL database, your favorite database...). Note that you'll need to update the hibernate.dialect property to match the Hibernate dialect appropriate for your data source. Check out the Database Guide for more info on setting up OBA with different databases.

The next entry sets up a geocoder used by the SMS interface. The default geocoder implementation has VERY limited functionality, but is sufficient for testing.

<bean id="externalGeocoderImpl" class="org.onebusaway.geocoder.impl.DefaultGeocoderImpl" />

The final entry specifies a default search location object:

<bean id="serviceArea" class="org.onebusaway.presentation.impl.DefaultServiceAreaServiceImpl" />

We use Google Web Toolkit (GWT) for writing much of the AJAX-ified tools and pages in the webapp. GWT development involves writing Java code that gets compiled to optimized Javascript. It's a development model that's too complicated to explain in specific detail here, so definitely check out the docs at the GWT website.

The one complication is that we are using a beta release of GWT 2.0. The upcoming release adds a lot of cool features, but brings some changes in development that we'll be discussing here.

The biggest change in GWT 2.0 is the addition of Out-of-Process-Hosted-Mode (OOPHM). Traditionally, when developing a GWT application, you ran the application in "hosted-mode", a custom web-browser component from Google that handled interleaving standard web elements (HTML, Javascript) with the dynamically compiled Java code. Hosted-mode let you debug your code using standard Java debugging tools (cool!). While that worked well enough, it made it a hassle when you wanted to easily debug your application within your standard browser using tools like Firebug for tweaking CSS and what not.

Google recognized these complaints and developed OOPHM. OOPHM works by using a browser-plugin to allow your GWT code to be run within your favorite browser while still allowing you to debug your GWT code using standard Java debugging tools.

This is a welcome change. Unfortunately, since GWT 2.0 hasn't officially been released yet, getting the OOPHM browser plugin installed and working can be a little tricky. Google has a wiki page with the latest:

http://code.google.com/p/google-web-toolkit/wiki/UsingOOPHM

Try the plugins and instructions listed there and let us know if you run into problems.

Most of the GWT application and module code can be found in the

org.onebusaway.webapp.gwt

package of the onebusaway-webapp source tree. Specific modules:

1. WhereStopFinderStandardApplication.gwt.xml - application entry point for the standard map-based web interface
2. MobileApplication.gwt.xml - application entry point for the experimental mobile-optimized web interface
3. OneBusAwayStandardApplication.gwt.xml - application entry point for the explore tool

To help make it easier to perform common GWT tasks, we are using the gwt-maven-plugin. The plugin takes care of normally tricky tasks like setting up your classpath for compiling and running GWT applications.

The module can be used from the maven command line (see the list of supported goals), but many of you will be running it from within Eclipse.

To do so, you need to setup a Maven run tasks. To run a specific Maven goal, right click on the onebusaway-webapp project, select "Run As" and then "Maven build...":

http://onebusaway.googlecode.com/svn/wiki/images/ModuleWebapp/RunProjectMavenBuild.png

This will bring up a screen where you can configure a specific Maven build task.

More details on tasks you might like to run follow:

The general pattern for running a GWT application in hosted mode is to use the "gwt:run" Maven goal. Configure a new Maven build task as specified in the previous section. Set the goal to "gwt:run" and then add the following parameters:

• gwt.noserver = true
• gwt.module = name of the gwt module to run
• runTarget = url of application entry point

For example, say we want to run the mobile-optimized gwt webapp MobileApplication. The full path of the module is org.onebusaway.webapp.gwt.MobileApplication and the URL entry point is http://localhost:8080/onebusaway-webapp/where/mobile/index.html. The configure Maven build task would then be:

http://onebusaway.googlecode.com/svn/wiki/images/ModuleWebapp/GwtRunExample.png

When you run the task, it will launch a Swing-based debug console and print a message like the following to the console:

Using a browser with the GWT Development Plugin, please browse to the following URL:
  http://localhost:8080/onebusaway-webapp/where/mobile/index.html?gwt.hosted=192.168.2.103:9997

Copy the URL into your browser and the browser will load the /onebusaway-webapp/where/mobile/index.html file like any other HTML file. However, that files references a GWT javascript module:

<script type="text/javascript" src="org.onebusaway.webapp.gwt.MobileApplication.nocache.js"></script>

The OOPHM GWT Development Plugin detects that you are loading GWT code and makes the appropriate connections back to the Hosted Mode process.

Note that you will already need to be running the general onebusaway-webapp as a server process to serve both static HTML files like the one above and also respond to incoming remote-procedure-calls from the GWT app.

The examples above assume you are running a onebusaway-webapp server instance locally at http://localhost:8080/onebusaway-webapp/. That's a reasonable way to set things up if you need to edit data and resources from the webapp itself, such as RPC methods, or if you need to run with your own data source.

If you just want to tweak the functionality of a GWT app and don't care so much about the back-end data source, you can work directly from our soak development server: http://soak.onebusaway.org/

The key here is to replace the http://localhost:8080/onebusaway-webapp/ in the above urls with http://soak.onebusaway.org/. That way, GWT will read initial data files from the soak webserver, but still run Java code locally. Additionally, RPC calls will go back to the soak server as well, freeing you from having to configure a datasource.

If you are doing development work with onebusaway-webapp and want to use the GWT modules in your running webapp (as opposed to modifying the GWT modules and running them within GWT dev mode), things are unfortunately more complicated than they could be. The GWT modules are included in source form, which means they are not compiled by default. To compile them, you need to run the following from the root onebusaway-application-modules parent module:

mvn -am -pl onebusaway-webapp package

This will compile and package the GWT modules in the onebusaway-webapp/target/gwt directory.

Once compiled, you need to copy them into your deployed webapp . Unfortunately, I haven't found a great way of automating this. I've introduced a helper Java class to assist in the task:

org.onebusaway.presentation.impl.CopyCompiledGwtResourcesMain

By running this class from within Eclipse, the class will examine the onebusaway-webapp/pom.xml and copy the GWT resources into the deployed webapp.

This application takes a single argument, which is the path to your deployed webapp. For example:

/Users/bdferris/oba/apache-tomcat-config/onebusaway-webapp/wtpwebapps/onebusaway-webapp

You can find the path to your deployed webapp in Eclipse by double-clicking on your server in your "Servers" tab where you deploy your apps, and this will open the server configuration window. Click on "Open launch configuration," and then click on the "Arguments" tab. Under VM arguments, find the "-Dwtp.deploy" argument and copy the following string, which will look like:

D:\Eclipse_Juno\.metadata\.plugins\org.eclipse.wst.server.core\tmp1\wtpwebapps

Then, just add "onebusaway-webapp" to the end, so you have the full path:

D:\Eclipse_Juno\.metadata\.plugins\org.eclipse.wst.server.core\tmp1\wtpwebapps\onebusaway-webapp

CRITICAL: For this to work properly, you must setting the Project to onebusaway-webapp in the Eclipse "Run As" dialog to make sure the CopyCompiledGwtResourcesMain is run relative to the onebusaway-webapp directory.

If you have ideas for improving this, I'm all ears.

Having problems? Check out our Troubleshooting page to see if we have a known solution.