Skip to content

Home

Jump to bottom
Oliver Schmid edited this page Jan 24, 2015 · 16 revisions

Welcome to the wiki of TWICE - Toolkit for Web-based Interactive Collaborative Environments. At this place, we will provide you with information about the toolkit and how it is thought to be used.

Getting started

This page shows how you can start with the development of collaborative web-applications in short time. ##Installation Instructions For an instructional tutorial video of how to set up the environment and how to launch the show case application, please visit the video section of this page.

To make use of the toolkit, check out the GIT repository into a local folder on your computer. Although it is possible to use other IDEs, we are using Eclipse and therefore integration is tested with this IDE. Therefore, the following steps are showing the example how to get the code running with Eclipse.

  1. Download Eclipse for JEE Developers from https://www.eclipse.org/downloads/ (you can use other versions as well but make sure, that the WTP is installed)
  2. Create a new workspace (define a different folder from the one into which you have cloned the GIT repository)
  3. Install the Eclipse plugin Maven integration for Eclipse WTP from market place
  4. Install the Eclipse plugin Google Plugin
  5. Optionally install the Eclipse plugin EGit for Git integration of the projects
  6. Import Existing projects into Eclipse from your cloned GIT repository folder (we recommend to include all of them)
  7. Run a Maven update project over all projects.

You could start the web application by simply clicking on Run As > Web Application now, but, since several modules make use of the new Servlet 3.0 annotations (it is very comfortable not to need to keep track of the servlet mappings in multiple projects within a single web.xml) and makes use of web sockets if available, we recommend to execute the application on an external server instead of the inbuilt Jetty server of the Google Development Mode. You therefore should:

  1. Download the servlet container of your choice (we recommend Tomcat 7.0 or newer: http://tomcat.apache.org/download-70.cgi)
  2. Install it at some place on your computer and configure it if necessary (e.g. if the standard ports are already in use)
  3. Configure your server in Eclipse ( Window -> Preferences -> Server -> Runtime Environments )
  4. Start the web application on the server ( Run As -> Run on server )
  5. Start the GWT mode of the web application ( Run As -> Web Application (running on an external server) )
  6. Define the External server root if necessary and start
  7. If you run the application for the first time (or if you execute it after a "Maven update project", you might get an error message that a folder does not exist. If so, you have to configure the GWT-launcher. Go to Run -> Run configurations... choose your launch configuration, go to the Arguments tab and change the value of the -war property to SOMEPATHONYOURMACHINE/target/m2e-wtp/web-resources
  8. If you launch the configuration through Run As -> Web Application (running on an external server) now, the error message should disappear and the development mode should launch.

For further details about how to develop with the Google Development Mode, please visit https://developers.google.com/web-toolkit/

Modules

There are multiple modules available fulfilling specific purposes in terms of provided collaborative functionalities. To get an overview about the different modules as well as their dependencies, we recommend to visit the Maven Sites.

The documentation is not yet complete and will continuously be improved.

Known issues

Currently, the multi pointer functionality requires the execution of a python web socket server. This server is provided in the package "MouseControlPython". The server should be started with the start.sh or start.bat (depending on the OS that you are using) with the additional port number (which should be defined as the port of the Java web container + 1 (if e.g. your Tomcat server runs on port 8080, the web socket server should run on 8081). Although the start.sh has been successfully tested on Linux systems, we have found issues when executing that script on Mac OS X. Since there is currently work going on to remove the requirement of the Python web socket server, we will not fix that shell script anymore (although if somebody has fixed it, we definitively would update it in the repository). At the very moment, a work around is to just hard code the installation specific path of the referenced python script within the shell script.

Library modules

Some modules are library modules. They only contain programming logic but do not have their own entry point or HTML page through which they would be accessible. If you want to integrate remote procedure services in such a library, you have to be aware, that the @RemoteServiceRelativePath annotation can not be used as in standards mode. This is, because you can not foresee the path the servlet will have in the application it is used. If your library module is called "foo" and your RemoteServiceRelativePath is "bar". You would define the servlet path of the server side implementation as "/foo/bar". But if you are using that library in your actual application (by inheriting it) and the module of that application is "xyz", the request will be sent to "xyz/bar" and therefore, the servlet will not respond properly. To solve this issue, we recommend to define the RemoteServiceRelativePath as "../foo/bar". Now the application xyz will request the path "/xyz/../foo/bar" which corresponds to "/foo/bar" and therefore actually calls our predefined servlet. It is good practice to use a well distinguishable path, since all inherited modules will end-up by using the same root - if two modules do have the same path by accident, this might result in errors at runtime. To make things even more beautiful, we recommend to handle the RPC-mappings the following way:

Define a static, final variable with the actual path in your RemoteService interface:

@RemoteServiceRelativePath(".." + YourService.PATH)
public interface YourService extends RemoteService {
     public static final String PATH = "/yourLibraryModule/yourService";

and reuse this static variable in the remote service servlet:

@WebServlet(urlPatterns = { YourService.PATH })
public class YourServiceImpl extends RemoteServiceServlet implements YourService {

Examples of application(s)

Next to the actual functionality projects, you will find projects with the name pattern "xxxStandalone". These are examples of how to apply the functionalities of a specific module. These projects are deployable as WAR-files.

As a more complete application, you find our show case application MindMap in the code repository. This application has been evaluated in an educational setting and provides fundamental functionalities for collaborative mindmap sessions involving a shared screen and multiple client devices.

Clone this wiki locally