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 email@example.com.
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.
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:
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.
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/
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/
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.
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.
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.
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."
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.
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):
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.
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
Only two Colored Trails GUI components, namely the board and phase table, have been developed thus far. While quite functional, these objects were designed mainly for demonstration purposes. Furthermore, the engineers behind CT3 are planning to completely overhaul the Colored Trails GUI, so it is likely that the WebCT Board and PhaseTable objects will be considerably modified before the official WebCT release. Nevertheless, limited discussion of these objects is included here for the benefit of developers new to GWT.
Here is the GWT code for the current Board GUI:
The ability to access underlying HTML element attributes removes the necessity of using Cascading Style Sheets (CSS) in WebCT. Any formatting possible through CSS can now be done using GWT widgets. For example, here is the code for the WebCT PhaseTable object:
The sections demarcated by the "Pay Special Attention Here" comments demostrate how the 'style' attribute for HTML elements can be set to values like "border-width:2px;padding:8px;border-style:solid;border-color:black;background-color:#ff69b4;-moz-border-radius:0px;font-weight:bold." Setting the 'style' attribute in this manner is the method by which the subtle visual details of WebCT will primarily be controlled.
Between the Jetty, GWT, and Java Servlet documentation, almost every aspect of the WebCT RPC system is thoroughly explained. It is particularly important to review the GWT documentation on RPCs to understand WebCT browser-server communication. Unfortunately, the WebCT servlet differs from the servlet examples that appear in GWT tutorials because of its reliance on Continuation objects.
WebCT's need for Continuation objects arises from inherent limitiations in the client-servlet model. Servlets by definition receive data from some source, perform actions, and then (possibly) return more data. Servlets are not designed to send data to a source without being prompted by a request from that source. Unfortunately, browsers connected to WebCT have no way to know if the CT game state has been changed without requesting a servlet service. Of course, this means that browser GUI displays could be kept up-to-date by repeatedly sending requests to the server. Polling at a regular interval, however, would clog the servlet than necessary for low activity games. The stress on the server would be further exacerbated by reducing the polling interval to the point where "lag" between game-state changes and browser GUI updates was unnoticeable.
Notice that the Update objects that are being returned to the browser during these asynchronous RPCs can essentially contain any possible game-state update: in the method's current form it checks if the update is related to the game starting, a board change, or a phase change. In terms of implementation, Update objects wrap and IsSerializable object and a String that is meant to identify the update type. The term serializable refers to the ability to convert Java objects to pure byte code and vice versa; serializability is an important attribute of Java object information that can be transmitted over the Internet. It should be noted that just because an object implements IsSerializable or can be cast to IsSerializable does not mean it is actually serializable by GWT standards. These standards are clarified in the GWT documentation and should be reviewed by anyone new to working with Update objects on the server side.
After thorough perusal of the listenForUpdates() code one might question why a StringWrapper object, rather than just a String, is sent back to the browser during a "set phase" type update. Such a wrapper exists because String objects, while actually serializable, are not assignable to an IsSerializable object (even using a cast). Therefore the String must be wrapped in an object that implements the IsSerializable interface. Similar wrappers must also be used for primitive types, Java's default primitive wrappers (like the Integer or Boolean classes), and Java collections.
Unfortunately, the servlet side code's getGameUpdate() response method is markedly different from anything found in a GWT tutorial:
Instead of extending the RemoteServiceServlet class as per most GWT tutorials, WebCTServiceImpl (WebCT's servlet class) extends AsyncRemoteServiceServlet, which is a class available from the org.mortbay.gwt package. The line "cont.suspend(0)" actually causes the AsyncRemoteServiceServlet to throw a special type of Exception object that the Jetty servlet container handles differently than other types of Exceptions. Usually when it catches an exception from a servlet request method, Jetty sends a failure response to the requesting browser. However, when the Exception thrown by cont.suspend() is caught, Jetty actually actually sends no response; instead it stores data that allows for the same request to be retried when the resume() method of the Continuation object that originally called suspend() is executed. In the case of WebCT, UpdateManager objects are responsible for calling Continuation objects' resume() methods. So when "um.registerAsRecipient(cont)" is executed, the specific UpdateManager "um" is being told to call the "resume()" method of the "cont" object as soon as "um" has new update content.
By the time an actual Update object is returned to the browser page, the servlet method "getGameUpdate(int clientPIN)" has been executed twice if the UpdateManager object did not have fresh updates when the method was originally called. Notice that the getGameUpdate browser request would never return a value if the corresponding WebCT client never generated a new Update object. If a positive int argument had been passed to the "cont.supend()," the Continuation would have automatically been resumed after a number of milliseconds matching the argument, at which point the servlet's getGameUpdate method would have been retried.
There are two WebCT client classes that, together, will allow participants to play CT over the web. WebPlayerAdaptorImpl implements the ColoredTrailsGUI interface and contains the client's necessary game discourse handlers. The code for WebPlayerAdaptorImpl is modeled after the class ctgui.original.GUI. WebPlayerAdaptorImpl contains an instance of a WebCTClientImpl, which is responsible for making changes to the game state and passing along appropriate GUI updates to its own UpdateManager object. The code for WebCTClientImpl is modeled after edu.harvard.eecs.airg.coloredtrails.client.ui.SimpleGUIAgentImpl.
WebCTClientImpl is, at this time, incomplete. Many of its current methods fail to pass GUI update data to the UpdateManager since the WebCT browser-side GUI library is not yet fully developed. For example, there is presently no transaction GUI that allows players to see their own chips or exchange chips with other players. As a result, no information about players' chips is being sent to clients' update managers at any point in the WebCTClientImpl code. A start game message, board information bundles, and phase information are all that the participant browser code is equipped to handle at the moment. The WebCT development team will give the WebCTClientImpl object a full array of update capabilities as soon as the browser GUI library is finished.
Developers playing with the current WebCTClientImpl source code should also note that the boardUpdated() method code uses a lot of value hardcoding that is not appropriate for all CT games (the current code has been developed in coordination with TheAutomatConfig configuration class). Instead of looking up the actual mapping of game objects to board images in the underlying CT objects, for example, such a mapping (BoardIconInfo object) is hardcoded with the following lines:
Also notice how the width, height, and priority-level (which will determine icon overlap on the board in the future) is also hard-coded for the IconInfo objects being added here. Ideally, dimensional and overlap setting information would instead be plucked out of the underlying CT game objects. The current CT3 trunk code, unfortunately, does not make such information available. Pending changes to the trunk will allow WebCTClientImpl's boardUpdated() method to be rewritten so that it functions correctly.