WebCT Project
Welcome to the WebCT wiki page. Like the project itself, this page is still under development. If you have questions about WebCT feel free to join the Colored Trails development group; as a member, you may send emails to coloredtrails-development@eecs.harvard.edu.
Contents
1. Overview
2. #Resources
3. #Get the Latest Version of WebCT
4. #Startup
6. #Jetty and the WebCT Servlet
Overview
WebCT is an effort to port the Colored Trails behavioral testbed to the web. The project will benefit future CT experimenters by allowing them to utilize participants in vastly separate locations and use the WebCT development team's own Harvard EECS server resources. In its final form, WebCT will enable researchers to construct experiments in which participants and administrators interact with the Colored Trails software through only a web browser.
At present the WebCT framework is incomplete. All the separate components that will be part of the final testbed have been substantially implemented, but important decisions have yet to be made regarding browser-side GUI elements, general Harvard EECS Colored Trails resources, and WebCT clients. The CT development team is, however, poised to begin constructing a final, user-friendly version of the project that will be compatable with current CT configuration classes. Given WebCT's unfinished status, this documentation page is more of an introduction to the project's different components than a "how-to" developer guide. When an experimenter-friendly version of the project is ready for distribution this page will be updated to enable researchers to immediately start building their own WebCT experiments.
In a nutshell, WebCT is simply the present CT3 trunk plugged into a standard Google Web Toolkit (GWT) browser-servlet web application framework. WebCT utilizes the same ColoredTrailsServer object as CT3 and does not prevent researchers from using previously developed custom configuration classes, agent clients, GUI clients, or game controllers. A Colored Trails web adaptor has been partially implemented as part of this project; in WebCTs distributable form, multiple instances of this adaptor will be wrapped by the WebCT Java Servlet so that remote procedure calls (RPCs) originating from user browsers can interact with respective clients without the use of Java Messaging Service (JMS) methods. To date, the WebCT development team has exclusively used GWT to generate the web browser GUIs and javascript that future experiments will employ. GWT and the Jetty continuation package have been utilized in order to create the Java Servlet that mediates between user web browsers and the CT client and server objects. It should be noted that the WebCT servlet is currently designed to be handled exclusively by a Jetty servlet container. The reason behind this constraint is detailed elsewhere in this document; the current servlet code will be revised after the release of the Java Servlet development package 3.0, at which point WebCT developers will be free to use any servlet container they choose.
The following figure depicts the architecture behind an example WebCT experiment:
A few key features of this architecture merit particular attention. First, the "Non-WebCT" client boxes refer to any possible CT client that was developed prior to WebCT. These could range from human GUI clients to game-specific agents, and there could potentially be any number of them at any location on the network containing the host machine of the CT server object. In the particular architecture shown above, one non-WebCT client is on the same physical host machine as the CT server while the other is not. As this diagram implies, it is possible for participants using Java GUI clients and participants using CT web browser pages to play the same exact game of Colored Trails at once.
Second, there are two different communication methods between different objects in the framework. The web browsers use RPCs (reliant on hyper text transfer protocol or "http") in order to send/receive data from the WebCT Java servlet. Meanwhile, the same JMS messaging system (reliant on transmission control protocol or "tcp") that currently powers CT3 remains responsible for the transmission of data between client adaptors and the server. The WebCT development team currently has no intention of modifying the JMS methods or their usage in the CT3 trunk code.
Finally, it is important to recognize that all of the web player adaptor clients are booted on the same JMS as the Jetty servlet container. Developers familiar with previous versions of Colored Trails have probably used Apache Ant commands like:
>>>ant runserver
>>>ant runclient1
>>>ant runclient2
Executed in sequence on commandlines for the same computer, these entries would start three different CT objects (ther server and two clients) such that each object is contained within its own Java Virtual Machine (JVM). In fact, many Colored Trails objects cannot share JVMs with certain other game objects. It is impossible, for example, to boot multiple GUI clients in the same Java process with the current Colored Trails trunk code. Furthermore, the CT server must exist on a separate JVM than any clients. Thus, the decision to design all the web clients to run on the same JVM is a somewhat stark departure from previous CT development philosophy.
Resources
To understand the WebCT framework end-to-end one must be familiar with a number of different technologies and tools that are referenced in this section. The official release of WebCT will not require that its users be familiar with all these different elements if they are conducting experiments that are compatible with the current CT trunk. However, the following links should prove valuable for future WebCT core developers and experimenters who need to modify trunk code to achieve their research goals.
Google Web Toolkit (GWT) -- http://code.google.com/webtoolkit/
-- http://google-web-toolkit.googlecode.com/svn/javadoc...
GWT compiles a subset of the Java language along with its own special modules into several versions of browser-specific Javascript that run within a specified HTML page. The WebCT project uses GWT to create all of its web pages and game GUIs. Web development with GWT is more similar to building Java GUIs with AWT and Swing than creating dynamic pages by writing raw HTML, Javascript, and CSS. Detailed GWT tutorials and documentation can be found through the first link. A shortcut to the actual Javadoc page for the com.google.gwt package (which contains all the browser user interface content) is found through the second link.
Eclipse -- http://www.eclipse.org/downloads/
Eclipse is the prefered IDE of the WebCT development team and happens to have a very nice GWT plug-in. The above link references the Eclipse download page.
Jetty Servlet Container -- http://www.mortbay.org/jetty/
Jetty 6.1.19 (or later) is the only servlet container that is compatible with WebCT in its current form because of its project's reliance on Continuation objects. The previous link connects to the Jetty homepage.
Jetty Continuation -- http://mvnrepository.com/artifact/org.mortbay.jetty/jetty-gwt/
-- http://docs.codehaus.org/display/JETTY/Continuations
-- http://docs.codehaus.org/display/JETTY/GWT
-- http://docs.codehaus.org/display/JETTY/GWT+RPC+Examples
These links reference pages related to the jetty-gwt Continuation package. Through the first link one can find the package downloads for different Jetty versions. Tutorials concerning the package's classes and Continuations can be found through the remaining links.
Java Servlet Technology -- http://java.sun.com/products/servlet/overview.html
The above link connects to the Sun Microsystems page for Java Servlets. From there one can find package downloads (which shouldn't be needed if you've downloaded GWT), API documentation, relevant articles, information about previous and future specifications, etc.
Java Core API Documentation -- http://java.sun.com/javase/6/docs/api/
The Java programming language is at the heart of WebCT (and, more generally, all of Colored Trails). Through the above link one can find the Javadoc for SDK 6.
HTML, Javascript, and CSS -- http://www.w3schools.com/
GWT removes much of the headache of writing HTML and Javascript but it's probably a good idea to understand these lower-level web application components. Furthermore, HTML element "style" attributes must sometimes be progmatically set to specific value strings to get certain WebCT widgets to behave correctly, so understanding CSS facilitates better understanding of browser Java code. This section's link references the W3School homepage for web-building tutorials and documentation. Generally speaking, web search engines seem capable of finding anything one needs to know about HTML, Javascript, and CSS.
Get the Latest Version of WebCT
The entire WebCT project is now available as a branch in the Colored Trails respository. Assuming that you have svn installed, enter the following command on your computer's terminal to obtain the WebCT development team's latest code and compiled WAR:
>>>svn checkout https://viki.eecs.harvard.edu/repos/ct3/branches/WebCT
Notice that downloading the project in this manner does not enable you to make official changes to the actual WebCT branch. If you are a member of the Colored Trails development team or have been granted the access priveleges necessary to make official repository changes, then "checkout" the project with:
>>>svn checkout https://viki.eecs.harvard.edu/repos/ct3/branches/WebCT --username <name>
Replace the tag <name> with your actual respository username. If you are a developer who is new to subversion, this tutorial should help you understand and utilize the tool.
Startup
WebCT has several different components that must currently be started independently. Note that this documentation assumes that the user has already downloaded and installed the Jetty-6.x or -7.x servlet container and the CT3 trunk on the experiment's host machine (the computer that will run both the servlet container and the Colored Trails server). Jetty installation documentation can be found on their website, and instructions for obtaining CT3, installing Apache Ant, and building the CT3 project have already been written by the Colored Trails development team. It is also assumed that programs like Java and Ant have already been added to the PATH environmental variable if the host machine uses Windows.
In order to host the WebCT application, the contents of the WAR directory in the WebCT download must be copied to "...some path.../Jetty-...version.../webapps/<FOO>" where "FOO" is a directory whose name you want associated with the experiment. One example of the web application's final path might be "/home/skye/jetty-6.1.19/webapps/WebCT." After the WAR content is copied, Jetty will host the WebCT application on its own startup.
Jetty Servlet Container
To start Jetty, simply issue the following command from its top-level directory:
>>> java -jar start.jar
You can now see WebCT in action: just open a browser and type in the URL bar "http://localhost:8080/<FOO>" where <FOO> is the name you gave to the directory containing the WAR content in the servlet container. So if the WAR content is in "/home/skye/jetty-6.1.19/webapps/WebCT", then type in the address bar "http://localhost:8080/WebCT."
Colored Trails Server
You can choose to start an instance of the Colored Trails Server from either your web browser or the command line. To start it from the browser click on the the "Create Experiment" button in the WebCT web application interface. Then click "Initialize CT Server."
To start the CT server from the command line or terminal simply enter the command "ant runserver" in the top directory of your CT3 installation.
Clients
As a reminder, WebCT clients are still incomplete. They currently only work in the context of the TheAutomatConfig game and, even then, they still have restricted functionality.
WebCT clients can only be initialized from the web. Simply click the "Join Experiment" button and then the "Register As Participant" button. The browser page should display the message, "Waiting for the game to begin..." When the game does begin, this message will disappear and the GUI objects will be displayed.
Normal Colored Trails player GUI clients can be started alongside WebCT clients. For example, you could start a GUI client with command (more information about starting clients can be found in a README in the agents directory of the CT3 trunk):
>>>ant runclient1
After connecting the Java client to the server from its own GUI and then registering a WebCT client with the server from a browser, the two clients should be capable of playing the same exact game of Colored Trails! Of course, the game has to be started before this can happen.
It is important to note that the WebCT servlet container is currently configured to not allow more than two clients to register through it. This restriction will obviously be lifted in the near future.
Starting TheAutomatConfig game
You can start the game from either the WebCT browser application or the command line. To start it from the browser enter the "Create Experiment" page and press the "Start CT Game" button. To start the game from the terminal or command line enter the following command in the top-level of your CT3 directory:
>>>ant runadmin -Dconfigfile=lib/adminconfig/TheAutomat.txt