mirror of
https://github.com/eclipse-sailing-analytics/sailing-analytics.git
synced 2026-10-08 13:20:57 +00:00
Merge remote-tracking branch 'server/master'
This commit is contained in:
Axel Uhl committed
commit
bdf7d69a19
15 files changed
+417
-227
No files matched your search
Binary file not shown.
@@ -18,16 +18,21 @@ Like businesses, sailors need the latest information to make strategic decisions
|
||||
* Information for Developers
|
||||
* [[Cook Book|wiki/cook-book]]
|
||||
* [[OnBoarding Information|wiki/onboarding]]
|
||||
* [[UI Tests with Selenium|wiki/selenium-ui-tests]]
|
||||
* [[Typical Development Scenarios|wiki/typical-development-scenarios]]
|
||||
* [[Server Replication|wiki/server-replication]]
|
||||
* [[Configure Races on Server|wiki/typical-development-scenarios]]
|
||||
* [[Development Environment|wiki/development-environment]]
|
||||
* [[Working with GWT Locally|wiki/local-gwt]]
|
||||
* [[Mobile Development|wiki/mobile-development]]
|
||||
* General Information
|
||||
* [[Architecture and Infrastructure|wiki/architecture-and-infrastructure]]
|
||||
* [[Sailing Domain Algorithms|wiki/sailing-domain-algorithms]]
|
||||
* [[Inventory|wiki/inventar-liste]]
|
||||
* [[Smartphone Tracking|wiki/smartphone-tracking]]
|
||||
* [[Racecommittee App|wiki/racecommittee-app]]
|
||||
* [[Web Services API|wiki/sailing-webservices]]
|
||||
* [[Theses (Bachelor, Master, ...)|wiki/theses]]
|
||||
* Planning and Event Information
|
||||
* [[Project Planning (bigger development)|wiki/planning]]
|
||||
* [[General Event Planning|wiki/general-event-planning]]
|
||||
@@ -40,4 +45,4 @@ Like businesses, sailors need the latest information to make strategic decisions
|
||||
* [Maven Repository Browser](http://maven.sapsailing.com/maven/)
|
||||
* [Main Sailing Website](http://www.sapsailing.com)
|
||||
* [Visitor Statistics](http://analysis.sapsailing.com/)
|
||||
* [Traffic and CPU for app01](http://mrtg.sapsailing.com/)
|
||||
* [Traffic and CPU for app01](http://mrtg.sapsailing.com/)
|
||||
Whitespace-only changes.
@@ -1,65 +1,73 @@
|
||||
# Development Environment
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## Git and Our Branches
|
||||
Our main Git repository lives at ssh://<user>@sapsailing.com/home/trac/git. For those working in the SAP corporate network and therefore unable to access the external sapsailing.com server using SSH, the repository contents are replicated on an hourly basis into ssh://dxxxxxx@git.wdf.sap.corp:29418/SAPSail/sapsailingcapture.git where dxxxxxx obviously is to be replaced by your D- or I- or C-user. You need to have an account at https://git.wdf.sap.corp:8080/ to be able to access this Git repository.
|
||||
|
||||
Small, obvious and non-disruptive developments are usually carried out immediately on our master branch. This branch is configured such that Maven can be used to run the tests inside the SAP corporate network. The master branch is never deployed onto the sapsailing.com server and hence has no corresponding /home/trac/servers/ subdirectory.
|
||||
|
||||
If a change looks reasonably good on the master branch and related JUnit tests or manual UI tests have succeeded locally, it is permissible to merge the master branch into the dev branch and run a central build on sapsailing.com. The dev branch is configured to run the Maven tests with direct Internet access. It can therefore also be used to run the tests locally if connected to the public Internet.
|
||||
|
||||
Ideally, the build should be run including the test cases. If the tests succeed , the branch can be installed and the corresponding server instance can be restarted. The branch can then also be promoted to the next level (dev-->test-->prod1/prod2). Note, that currently re-starting a server instance may require re-loading the races that were previously loaded, particularly for the prod1 and prod2 instances, because several externally-announced URLs point to them.
|
||||
|
||||
We typically promote the changes to the next branch by also merging the current master branch into the next-"higher" branch. This should lead to equivalent results compared to merging the "previous" branch (e.g., dev) into the "next" branch (e.g., test). The branches differ largely in the configurations used for the servers, particularly the port assignments for the Jetty web server, the UDP ports used for listening for Expedition wind messages, and the queue names used for the replication based on RabbitMQ (see also Scale-Out through Replication).
|
||||
|
||||
## Eclipse Setup, Required Plug-Ins
|
||||
We use Eclipse as our development environment. Using a different IDE would make it hard to re-use the project configurations (.project and .classpath files which are specific to Eclipse) as well as the GWT plug-in which assists in locally compiling and refactoring the GWT code, in particular the RPC code.
|
||||
|
||||
The recommended and tested Eclipse version is currently Indigo (3.7). Colleagues have reported that they succeeded with a Juno (3.8/4.x) set-up as well.
|
||||
|
||||
To get started, install Eclipse with at least PDE, Git, GWT (use http://dl.google.com/eclipse/plugin/3.7 as update site) and JSP editing support enabled. Eclipse Maven support is not recommended as in many cases it has caused trouble with the local Eclipse build.
|
||||
|
||||
## Target Platform
|
||||
After the Eclipse installation and importing all projects under java/ from Git, it is required to set the target platform in Eclipse (Window --> Preferences --> Plugin Development --> Target Platform). The project com.sap.sailing.targetplatform contains "Race Analysis Target (IDE)" as target platform definition. It uses a number of p2 update sites and defines the OSGi bundles that constitute the target platform for the application. If this is not set in Eclipse, the local build environment assumes that the developer wants to implement Eclipse plug-ins and offers the entire set of Eclipse plug-ins and only those as the target platform which doesn't make any sense for our application.
|
||||
|
||||
Major parts of our target platform are hosted on sapsailing.com as a p2 repository which makes it possible to have only one central target platform configuration used by everyone. The target platform can be re-built, e.g., after adding another bundle to it, using the script in com.sap.sailing.targetplatform/scripts.
|
||||
|
||||
It then needs to be installed again (by using a tool like scp for instance) to the /home/trac/p2-repositories directory from where it is exposed as http://sapcoe-app01.pironet-ndh.com/p2/sailing/ by the Apache web server. After such a change, all developers need to reload the target platform into their Eclipse environment.
|
||||
|
||||
## Maven Build and Tests
|
||||
We use Maven to build our software and run our JUnit tests. The global setting.xml file to install in everyone's ~/.m2 directory is checked into the top-level Git folder. The checked-in copy assumes the developer is using Maven inside the SAP corporate network. If not, uncomment the <proxy> tag in the settings.xml file. See also section Git and Our Branches for details on which branch is configured to work in which network setup.
|
||||
|
||||
We have a top-level Maven pom.xml configuration file in the root folder of our Git workspace. It delegates to the pom.xml file in the java/ folder where all the bundle projects are defined. We rely on the Tycho Maven plug-in to build our OSGi bundles, also known as the "manifest-first approach." The key idea is to mainly develop using Eclipse means, including its OSGi manifest editing capabilities, and keep the Maven infrastructure as simple as possible, deriving component dependencies from the OSGi manifests. See the various pom.xml files in the projects to see the project-specific settings. By and large, a pom.xml file for a bundle needs to have the bundle name and version defined (we currently have most bundles at version 1.0.0.qualifier in the manifest or 1.0.0.SNAPSHOT in Maven), and whether the bundle is a test or non-test bundle, expressed as the packaging type which here can be one of eclipse-plugin or ecplise-test-plugin.
|
||||
|
||||
Test plugins automatically have their tests executed during a Maven build unless the command-line option -Dmaven.test.skip=true argument is specified. It is generally a good idea to launch the Maven command using the -fae option which asks Maven to continue until the end, even if errors or failures occurred on the way, failing at the end if any failures occurred. This can save numerous round trips and is useful in case of known and temporarily acceptable test failures.
|
||||
|
||||
The Maven plug-in for the GWT compilation doesn't reliably perform a dependency check. It is therefore recommended to remove all contents of the java/com.sap.sailing.gwt.ui/com.sap.sailing.* folders (basically, all GWT compiler output) before launching the Maven build. A good command line for the Maven build from the java/ subdirectory in your local environment when outside the SAP VPN is this:
|
||||
|
||||
`rm -rf com.sap.sailing.gwt.ui/com.sap.sailing.*; mvn -fae -P debug.without-proxy clean install 2>&1 | tee log`
|
||||
|
||||
Inside the SAP VPN you may want to use a different profile which accounts for the proxies that have to be used:
|
||||
|
||||
`rm -rf com.sap.sailing.gwt.ui/com.sap.sailing.*; mvn -fae -P debug.with-proxy clean install 2>&1 | tee log`
|
||||
|
||||
When building on sapsailing.com you have to explicitly specify the settings.xml file from the git workspace. You also have to make sure the DISPLAY environment variable is set to ":2.0" to send test browsers to a VNC display. Should the GWT build fail because it cannot open enough files, ensure the "ulimit -n" output is at least 4096 to enable the GWT compiler to assemble the resource sets which consist of many files that all need to be opened concurrently. Currently, the maximum value for "ulimit -n" is configured in /etc/security/limits.conf and is set to 16384. This specified the maximum amount to which a user's shell can set this value. The ~trac/.bash_profile contains a "ulimit -n 4096" command, but when running "screen" the shells usually are no login shells. You need to make sure you run ~trac/.bash_profile in the build shell to set the limit of open files to at least 4096. Then issue `rm -rf com.sap.sailing.gwt.ui/com.sap.sailing.*; mvn -fae -s /home/trac/git/settings.xml -P debug.without-proxy clean install 2>&1 | tee log`
|
||||
|
||||
All these build lines also creates a log file with all error messages, just in case the screen buffer is not sufficient to hold all scrolling error messages.
|
||||
|
||||
## Product and Features
|
||||
The result of the build process is a p2 repository with a product consisting of a number of features. The product configuration is provided by the file raceanalysis.product in the com.sap.sailing.feature.p2build project. In its dependencies it defines the features of which it is built, which currently are com.sap.sailing.feature and com.sap.sailing.feature.runtime, each described in an equal-named bundle.
|
||||
|
||||
The feature specified by com.sap.sailing.feature lists the bundles we develop ourselves as part of the project. The com.sap.sailing.feature.runtime feature lists those 3rd-party bundles from the target platform which are required by the product.
|
||||
|
||||
## External Libraries
|
||||
|
||||
### Highcharts and jQuery
|
||||
We use the Highcharts library to present graphs to the user. These graphs are used on the RaceBoardPanel and (at the time of writing still under development) the PolarSheetsPanel. In the past, there were difficulties concerning the versions of the three interacting libraries:
|
||||
|
||||
* The GWT Highcharts Wrapper – The source code can be found in our project and it’s slightly modified to match our scenario
|
||||
* The actual Highcharts Library
|
||||
* The jQuery Library
|
||||
|
||||
To support polar diagrams we use version 3.5.0 of the wrapper. This version is tested with version 2.3.3 of the Highcharts library. We tried using 2.3.5 but that led to problems when resizing the RaceBoard.
|
||||
|
||||
Highcharts uses the jQuery library. We do know that version 1.4.2 does NOT work with the versions of Highcharts mentioned above. Multiple yAxis are not initialized correctly. We know use version 1.5.2 of this library.
|
||||
# Development Environment
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## Git and Our Branches
|
||||
Our main Git repository lives at ssh://<user>@sapsailing.com/home/trac/git. For those working in the SAP corporate network and therefore unable to access the external sapsailing.com server using SSH, the repository contents are replicated on an hourly basis into ssh://dxxxxxx@git.wdf.sap.corp:29418/SAPSail/sapsailingcapture.git where dxxxxxx obviously is to be replaced by your D- or I- or C-user. You need to have an account at https://git.wdf.sap.corp:8080/ to be able to access this Git repository.
|
||||
|
||||
Small, obvious and non-disruptive developments are usually carried out immediately on our master branch. This branch is configured such that Maven can be used to run the tests inside the SAP corporate network. The master branch is never deployed onto the sapsailing.com server and hence has no corresponding /home/trac/servers/ subdirectory.
|
||||
|
||||
If a change looks reasonably good on the master branch and related JUnit tests or manual UI tests have succeeded locally, it is permissible to merge the master branch into the dev branch and run a central build on sapsailing.com. The dev branch is configured to run the Maven tests with direct Internet access. It can therefore also be used to run the tests locally if connected to the public Internet.
|
||||
|
||||
Ideally, the build should be run including the test cases. If the tests succeed , the branch can be installed and the corresponding server instance can be restarted. The branch can then also be promoted to the next level (dev-->test-->prod1/prod2). Note, that currently re-starting a server instance may require re-loading the races that were previously loaded, particularly for the prod1 and prod2 instances, because several externally-announced URLs point to them.
|
||||
|
||||
We typically promote the changes to the next branch by also merging the current master branch into the next-"higher" branch. This should lead to equivalent results compared to merging the "previous" branch (e.g., dev) into the "next" branch (e.g., test). The branches differ largely in the configurations used for the servers, particularly the port assignments for the Jetty web server, the UDP ports used for listening for Expedition wind messages, and the queue names used for the replication based on RabbitMQ (see also Scale-Out through Replication).
|
||||
|
||||
## Eclipse Setup, Required Plug-Ins
|
||||
We use Eclipse as our development environment. Using a different IDE would make it hard to re-use the project configurations (.project and .classpath files which are specific to Eclipse) as well as the GWT plug-in which assists in locally compiling and refactoring the GWT code, in particular the RPC code.
|
||||
|
||||
The recommended and tested Eclipse version is currently Indigo (3.7). Colleagues have reported that they succeeded with a Juno (3.8/4.x) set-up as well.
|
||||
|
||||
To get started, install Eclipse with at least PDE, Git, GWT (use http://dl.google.com/eclipse/plugin/3.7 as update site) and JSP editing support enabled. Eclipse Maven support is not recommended as in many cases it has caused trouble with the local Eclipse build.
|
||||
|
||||
## Target Platform
|
||||
After the Eclipse installation and importing all projects under java/ from Git, it is required to set the target platform in Eclipse (Window --> Preferences --> Plugin Development --> Target Platform). The project com.sap.sailing.targetplatform contains "Race Analysis Target (IDE)" as target platform definition. It uses a number of p2 update sites and defines the OSGi bundles that constitute the target platform for the application. If this is not set in Eclipse, the local build environment assumes that the developer wants to implement Eclipse plug-ins and offers the entire set of Eclipse plug-ins and only those as the target platform which doesn't make any sense for our application.
|
||||
|
||||
Major parts of our target platform are hosted on sapsailing.com as a p2 repository which makes it possible to have only one central target platform configuration used by everyone. The target platform can be re-built, e.g., after adding another bundle to it, using the script in com.sap.sailing.targetplatform/scripts.
|
||||
|
||||
It then needs to be installed again (by using a tool like scp for instance) to the /home/trac/p2-repositories directory from where it is exposed as http://p2.sapsailing.com/p2/sailing/ by the Apache web server. After such a change, all developers need to reload the target platform into their Eclipse environment.
|
||||
|
||||
## Maven Build and Tests
|
||||
We use Maven to build our software and run our JUnit tests. The global setting.xml file to install in everyone's ~/.m2 directory is checked into the top-level Git folder. The checked-in copy assumes the developer is using Maven inside the SAP corporate network. If not, uncomment the <proxy> tag in the settings.xml file. See also section Git and Our Branches for details on which branch is configured to work in which network setup.
|
||||
|
||||
We have a top-level Maven pom.xml configuration file in the root folder of our Git workspace. It delegates to the pom.xml file in the java/ folder where all the bundle projects are defined. We rely on the Tycho Maven plug-in to build our OSGi bundles, also known as the "manifest-first approach." The key idea is to mainly develop using Eclipse means, including its OSGi manifest editing capabilities, and keep the Maven infrastructure as simple as possible, deriving component dependencies from the OSGi manifests. See the various pom.xml files in the projects to see the project-specific settings. By and large, a pom.xml file for a bundle needs to have the bundle name and version defined (we currently have most bundles at version 1.0.0.qualifier in the manifest or 1.0.0.SNAPSHOT in Maven), and whether the bundle is a test or non-test bundle, expressed as the packaging type which here can be one of eclipse-plugin or ecplise-test-plugin.
|
||||
|
||||
Test plugins automatically have their tests executed during a Maven build unless the command-line option -Dmaven.test.skip=true argument is specified. It is generally a good idea to launch the Maven command using the -fae option which asks Maven to continue until the end, even if errors or failures occurred on the way, failing at the end if any failures occurred. This can save numerous round trips and is useful in case of known and temporarily acceptable test failures.
|
||||
|
||||
The Maven plug-in for the GWT compilation doesn't reliably perform a dependency check. It is therefore recommended to remove all contents of the java/com.sap.sailing.gwt.ui/com.sap.sailing.* folders (basically, all GWT compiler output) before launching the Maven build. A good command line for the Maven build from the java/ subdirectory in your local environment when outside the SAP VPN is this:
|
||||
|
||||
buildAndUpdateProduct.sh build
|
||||
|
||||
which basically does something like
|
||||
|
||||
`rm -rf com.sap.sailing.gwt.ui/com.sap.sailing.*; mvn -fae -P debug.without-proxy clean install 2>&1 | tee log`
|
||||
|
||||
Inside the SAP VPN you may want to use a different profile which accounts for the proxies that have to be used:
|
||||
|
||||
buildAndUpdateProduct.sh -p build
|
||||
|
||||
The buildAndUpdateProduct.sh script can be found in the top-level configuration/ directory in git. It has been used successfully in Linux and Cygwin environments.
|
||||
|
||||
When building on sapsailing.com you should stick with the buildAndUpdateProduct.sh script. It makes a lot of settings that are necessary, such as specifying the settings.xml file to use for the Maven build. For the Selenium tests to succeed you have to make sure the DISPLAY environment variable is set to ":2.0" to send test browsers to a VNC display. Should the GWT build fail because it cannot open enough files, ensure the "ulimit -n" output is at least 4096 to enable the GWT compiler to assemble the resource sets which consist of many files that all need to be opened concurrently. Currently, the maximum value for "ulimit -n" is configured in /etc/security/limits.conf and is set to 16384. This specified the maximum amount to which a user's shell can set this value. The ~trac/.bash_profile contains a "ulimit -n 4096" command, but when running "screen" the shells usually are no login shells. You need to make sure you run ~trac/.bash_profile in the build shell to set the limit of open files to at least 4096. Then issue the respective buildAndUpdateProduct.sh command line.
|
||||
|
||||
All these build lines also creates a log file with all error messages, just in case the screen buffer is not sufficient to hold all scrolling error messages.
|
||||
|
||||
## Product, Features and Target Platform
|
||||
The result of the build process is a p2 repository with a product consisting of a number of features. The product configuration is provided by the file raceanalysis.product in the com.sap.sailing.feature.p2build project. In its dependencies it defines the features of which it is built, which currently are com.sap.sailing.feature and com.sap.sailing.feature.runtime, each described in an equal-named bundle. The feature specified by com.sap.sailing.feature lists the bundles we develop ourselves as part of the project. The com.sap.sailing.feature.runtime feature lists those 3rd-party bundles from the target platform which are required by the product.
|
||||
|
||||
The [target platform](#Target-Platform) is defined in the various flavors for local and central environments in com.sap.sailing.targetplatform/definitions/*.target. It mainly uses Eclipse p2 repositories and our own p2 repository at http://p2.sapsailing.com/p2/sailing/ where we store those bundles required by our runtime which cannot be found as OSGi bundles in any other public p2 repository of which we are aware.
|
||||
|
||||
This p2 repository at sapsailing.com can be re-built and correspondingly extended by the process explained [here](wiki/typical-development-scenarios#Adding-a-Bundle-to-the-Target-Platform).
|
||||
|
||||
## External Libraries
|
||||
|
||||
### Highcharts and jQuery
|
||||
We use the Highcharts library to present graphs to the user. These graphs are used on the RaceBoardPanel and (at the time of writing still under development) the PolarSheetsPanel. In the past, there were difficulties concerning the versions of the three interacting libraries:
|
||||
|
||||
* The GWT Highcharts Wrapper – The source code can be found in our project and it’s slightly modified to match our scenario
|
||||
* The actual Highcharts Library
|
||||
* The jQuery Library
|
||||
|
||||
To support polar diagrams we use version 3.5.0 of the wrapper. This version is tested with version 2.3.3 of the Highcharts library. We tried using 2.3.5 but that led to problems when resizing the RaceBoard.
|
||||
|
||||
Highcharts uses the jQuery library. We do know that version 1.4.2 does NOT work with the versions of Highcharts mentioned above. Multiple yAxis are not initialized correctly. We know use version 1.5.2 of this library.
|
||||
+1
-1
@@ -9,7 +9,7 @@ The script `/home/gollum/wiki/serve.sh` can be executed to either start or resta
|
||||
Accessing this wiki is normally only allowed for authenticated users. If you want to share your work with others not having an account here then you can just request making a given url publicly available. On the server this is done by simply putting a new line to `/home/gollum/wiki/public.txt`.
|
||||
|
||||
### Creating a New Account
|
||||
A new account can be created by adding a new entry to `/home/gollum/wiki/users.yml`. The password there is encrypted using sha1sum (`echo -n "password" | sha1sum`).
|
||||
A new account can be created by adding a new entry to `/home/gollum/wiki/users.yml`. The password there is encrypted using sha1sum (`echo -n "password" | sha1sum`) or, for those who don't happen to have sha1sum available, using an online SHA1 generator such as [this one](http://www.sha1-online.com/).
|
||||
|
||||
### Editing
|
||||
You can edit information here freely but do not leave any nonsense here.
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# Working with GWT Locally
|
||||
|
||||
We're using GWT in a slightly non-standard way, combining it with the merits of OSGi and using separate GWT modules that are shared between server and client (such as com.sap.sailing.domain.common). Particularly the combination of GWT with OSGi comes with a few special arrangements and things that are noteworthy.
|
||||
|
||||
## Some Background (javax.servlet Version)
|
||||
|
||||
GWT comes with a built-in copy of the javax.servlet packages. However, in our environment, the servlet engine is provided by the Jetty bundles whose javax.servlet versions don't necessarily match with the one provided by the GWT version we use. To make the build use the javax.servlet version provided at runtime by Jetty, using the GWT classpath container that usually is added automatically to all GWT projects is detrimental to a proper build. That's why we have removed it in particular from the com.sap.sailing.gwt.ui project.
|
||||
|
||||
Since the OSGi manifest dependencies still require javax.servlet, the Eclipse and Maven builds now use the correct Jetty-provided version of javax.servlet. However, not having the GWT classpath container on a GWT project's classpath unfortunately makes it impossible to use the GWT Eclipse plugin's neat GWT Compile feature.
|
||||
|
||||
## Local GWT Compile
|
||||
|
||||
As a workaround, use the buildAndUpdateProduct.sh script found in the top-level configuration/ directory in git. Together with the -t and -c options (no tests, no cleaning), the compilation speed may be found acceptable. If you really urgently need to compile GWT locally on a regular basis and would like to speed up compilation, please consider temporarily editing java/com.sap.sailing.gwt.ui/pom.xml to reduce the number of modules and permutations to be compiled.
|
||||
|
||||
## Debugging GWT
|
||||
|
||||
One of the great strengths of GWT is the use of Eclipse as a Java source-level debugging environment. To enjoy this feature, launch the SailingServer launch config appropriate for your environment (Proxy / No Proxy), then launch the SailingGWT launch configuration in debug mode. After a while it will show a "Development Mode" view that shows all entry points that have been initialized. Double-click on the one you want to debug, and your default browser (hopefully FireFox, because with other browsers the GWT debug plugin tends to be not very stable or not even present) will open.
|
||||
|
||||
You can set breakpoints in your GWT Java code and inspect values for suspended threads as usual for any Java development.
|
||||
|
||||
Note the reduced performance which is largely due to the way the Java VM and the browser plug-in communicate. In particular, many fine-grained changes to the DOM can be quite costly. Therefore, if you're only interested in server-side debugging, consider [compiling](#Local-GWT-Compile) the GWT code for better performance.
|
||||
@@ -1,9 +1,18 @@
|
||||
# Mobile Development
|
||||
|
||||
The native Android projects are in the mobile/ folder in git which is next to the java/ folder. To build them successfully, you need to install the Android SDK which is available [here](http://developer.android.com/sdk/index.html). Also, you need to use the Eclipse update site https://dl-ssl.google.com/android/eclipse and install the Eclipse ADT plugins.
|
||||
See [On Boarding](onboarding#Additional-steps-required-for-Android-projects) how to set up your build environment for mobile development.
|
||||
|
||||
Currently (2013-07-18), the Race Committee App uses the Google APIs Version 13 (Android 3.2) which you need to install through the Android SDK Manager (see Eclipse toolbar after installing the Eclipse ADT plugin). In the Android Virtual Device manager which can also be found in the Eclipse toolbar you can configure an emulated device. One successful approach was using a 10.1" WXGA (Tablet) device in the emulator configuration and choose "Google APIs (Google Inc.) - API Level 13" as the target.
|
||||
Besides running the application on a plugged-in device there are multiple options for using an emulator:
|
||||
|
||||
After that it should be possible to choose "Debug as --> Android application" in the com.sap.sailing.racecommittee.app project's context menu, then pick the emulator you're previously created.
|
||||
|
||||
If you want to run the app against your locally-running server, go into the Settings and choose http://10.0.2.2:8888 as the JSON URL. See also [here](http://developer.android.com/tools/devices/emulator.html#emulatornetworking) for more details on the emulator's network behavior.
|
||||
* Android Virtual Device (AVD)
|
||||
* Default Android emulator
|
||||
* Comes with the ADT and is well integrated into Eclipse
|
||||
* In the AVD manager which can be found in the Eclipse toolbar you can configure an emulated device. Create a 10.1" WXGA (Tablet) device in the emulator configuration and choose "Google APIs (Google Inc.) - API Level 13" as the target.
|
||||
* Use virtual device as described in [[On Boarding|wiki/onboarding]]
|
||||
* If you want to run the app against your locally-running server, go into the Settings and choose http://10.0.2.2:8888 as the JSON URL. See also [here](http://developer.android.com/tools/devices/emulator.html#emulatornetworking) for more details on the emulator's network behavior.
|
||||
* Genymotion (AndroVM)
|
||||
* VirtualBox-based Android emulator
|
||||
* Currently in free beta phase; way faster than AVD; better support for Google Apps (e.g. Maps) and easy access to sensor features (e.g. setting GPS info)
|
||||
* Register at http://www.genymotion.com/, download and install virtual device "WXGA 10.1 Tablet - 4.1.1 - with Google Apps - API 16 - 1280x800" with 160dpi
|
||||
* If you want to run the app against your locally-running server, check the IP address of your host machine for the VirtualBox network interface. Use this IP when you are configuring the app.
|
||||
* Use virtual device as described in [[On Boarding|wiki/onboarding]]
|
||||
+104
-102
@@ -1,102 +1,104 @@
|
||||
# OnBoarding Information
|
||||
|
||||
This document describes the onboarding process for a new team member (developer)
|
||||
|
||||
### Race Analysis Development Setup
|
||||
|
||||
#### Installations
|
||||
|
||||
1. Eclipse (e.g. Eclipse Classic 4.2.1 (Juno)), http://www.eclipse.org
|
||||
2. Eclipse Extensions
|
||||
* Install Eclipse GWT should be version 2.5 (https://developers.google.com/eclipse/docs/download)
|
||||
3. Git (e.g. msysGit for Windows v1.7.10), http://git-scm.com
|
||||
4. MongoDB (e.g. Production Release 2.0.4), download: http://www.mongodb.org/
|
||||
5. RabbitMQ, download from http://www.rabbitmq.com/. Requires Erlang to be installed. RabbitMQ installer will assist in installing Erlang.
|
||||
6. JDK 1.6 (Java SE 6), http://jdk6.java.net (for GWT)
|
||||
7. JDK 1.7 (Java SE 7), http://jdk7.java.net
|
||||
8. Maven 3, http://maven.apache.org
|
||||
|
||||
#### Further optional but recommended installations
|
||||
|
||||
1. Cygwin, http://www.cygwin.com/
|
||||
2. Eclipse Mylyn Bugzilla extension
|
||||
3. kdiff3 (git tool)
|
||||
4. Firebug (javascript & .css debugging)
|
||||
|
||||
#### Accounts
|
||||
|
||||
1. Git Account
|
||||
- Register yourself as a Git user in the SAP-Git under: https://git.wdf.sap.corp:8080/
|
||||
- Ask the Git administrator (Axel Uhl) to get on the list of enabled committers
|
||||
|
||||
2. Bugzilla
|
||||
- Ask the Bugzilla administrator (Frank Mittag, Axel Uhl) to create a bugzilla account for you.
|
||||
- Bugzilla url: http://sapcoe-app01.pironet-ndh.com/bugzilla/
|
||||
|
||||
3. Race Analysis user
|
||||
- Add yourself as an user to the Race Analysis suite by adding a Jetty user in the file
|
||||
java\target\configuration\jetty\etc\realm.properties
|
||||
|
||||
#### Steps to build and run the Race Analysis Suite
|
||||
|
||||
1. Get the content of the git repository
|
||||
- Clone the repository to your local file system from `ssh://[SAP-User]@git.wdf.sap.corp:29418/SAPSail/sapsailingcapture.git` or `ssh://[user]@sapsailing.com/home/trac/git`
|
||||
|
||||
2. Check out the 'master' branch from the git repository. The 'master' branch is the main development branch. Please check that you start your work on this branch.
|
||||
|
||||
3. Setup and configure Eclipse
|
||||
- Make absolutely sure to import CodeFormatter.xml (from $GIT_HOME/java) into your Eclipse preferences (Preferences->Java->Code Style->Fortmatter)
|
||||
- Install the Eclipse GWT-Plugin (now called Google Plugin for Eclipse, you need the Gogle WebToolkit SDK from the same update site, too)
|
||||
- Install Eclipse eGit (optional)
|
||||
- Check that JDK 1.7 is available and has been set for compilation in Eclipse
|
||||
- Check that the both JDKs are available (Windows->Preferences->Java->Installed JREs)
|
||||
- Check that JDK 1.6 has been matched to JavaSE-1.6 and that JDK 1.7 has been matched to JavaSE-1.7 (...>Installed JREs>Execution Environments)
|
||||
- It is also possible to match the SAPJVM 6 or 7 to the JavaSE-1.6 (for profiling purposes)
|
||||
- Import all Race Analysis projects from the /java(!!!) subdirectory of the git main folder
|
||||
- Set the Eclipse target platform to race-analysis-p2-ide-local.target (located in com.sap.sailing.targetplatform/definitions)
|
||||
- Wait until the target platform has been resolved completely
|
||||
- In the project com.sap.sailing.gwt.ui create a new subfolder "classes" in the folder WEB-INF
|
||||
- Rebuild all projects
|
||||
|
||||
4. Run the Race Analysis Suite
|
||||
- Start the MongoDB
|
||||
- Start the appropriate Eclipse launch configuration (e.g. 'Sailing Server (Proxy)')
|
||||
- Start the GWT UI
|
||||
|
||||
5. Within the Race Analysis Suite
|
||||
- For TracTrac Events: (Date 27.11.2012) Use Live URI tcp://10.18.22.156:4412, Stored URI tcp://10.18.22.156:4413, JSON URL http://germanmaster.traclive.dk/events/event_20120905_erEuropean/jsonservice.php
|
||||
- Press List Races
|
||||
|
||||
#### Maven Setup
|
||||
Copy the settings.xml from the top-level git folder to your ~/.m2 directory and adjust the proxy settings accordingly. Make sure the mvn executable you installed above is in your path. Open a shell (preferrably a git bash or a cygwin bash), cd to the java/ subfolder of the git workspace and issue "mvn -fae clean install". This should build the software and run all the tests. If you want to avoid the tests being executed, run "mvn -Dmaven.test.skip=true -fae clean install". If you want to make sure the GWT compiler really re-builds all artifacts, remove all java/com.sap.sailing.gwt.ui/com.sap.sailing.gwt.ui.* directories, then re-build.
|
||||
|
||||
#### Further hints
|
||||
- Configure Eclipse to use Chrome or Firefox as the default browser
|
||||
- Install the GWT Browser Plugin (Chrome or Firefox) for the GWT Development mode
|
||||
|
||||
#### Additional steps required for Android projects
|
||||
|
||||
To ensure that all components of the Analysis Suite are working, you should also import all Android projects into your workspace. There are some additional requirements to enable the build process of these projects.
|
||||
|
||||
1. Add the Android Development Tools (ADT) plugin to your Eclipse IDE
|
||||
- In Eclipse click Help -> Install New Software -> Add and enter https://dl-ssl.google.com/android/eclipse/
|
||||
- Select the Developer Tools and install
|
||||
- After restarting Eclipse the "Welcome to Android Development" window should help you with installing the Android SDK
|
||||
- It is also possible to download the Android SDK separately from http://developer.android.com/sdk/index.html ("Use an existing IDE")
|
||||
2. Setup the Android SDK
|
||||
- In Eclipse press Window -> Android SDK Manager
|
||||
- Ensure that everything of "Tools" is installed
|
||||
- Install everything of "Android 3.2 API 13"
|
||||
- Install "Android Support Library" (Extras), "Google Play Services" (Extras) and "Google USB Driver" (Extras)
|
||||
3. Import the Android projects into your workspace
|
||||
- Android projects can be found in the /mobile subdirectory
|
||||
|
||||
To deploy an Android project (for example com.sap.sailing.racecommittee.app) to a device
|
||||
1. Plug-in the device
|
||||
- Development mode must be enabled on the device
|
||||
- For certain device/OS combinations additional device drivers are needed
|
||||
- You can check if the device is detected correctly by checking the "Devices" tab of the "DDMS" Eclipse perspective.
|
||||
2. Start a run configuration of the project
|
||||
3. Select your attached device in the device selection screen
|
||||
4. The app should be started after deployment
|
||||
|
||||
# OnBoarding Information
|
||||
|
||||
This document describes the onboarding process for a new team member (developer)
|
||||
|
||||
### Race Analysis Development Setup
|
||||
|
||||
#### Installations
|
||||
|
||||
1. Eclipse (e.g. Eclipse Classic 4.2.1 (Juno)), http://www.eclipse.org
|
||||
2. Eclipse Extensions
|
||||
* Install Eclipse GWT should be version 2.5 (https://developers.google.com/eclipse/docs/download)
|
||||
3. Git (e.g. msysGit for Windows v1.7.10), http://git-scm.com
|
||||
4. MongoDB (e.g. Production Release 2.0.4), download: http://www.mongodb.org/
|
||||
5. RabbitMQ, download from http://www.rabbitmq.com/. Requires Erlang to be installed. RabbitMQ installer will assist in installing Erlang.
|
||||
6. JDK 1.6 (Java SE 6), http://jdk6.java.net (for GWT)
|
||||
7. JDK 1.7 (Java SE 7), http://jdk7.java.net
|
||||
8. Maven 3, http://maven.apache.org
|
||||
|
||||
#### Further optional but recommended installations
|
||||
|
||||
1. Cygwin, http://www.cygwin.com/
|
||||
2. Eclipse Mylyn Bugzilla extension
|
||||
3. kdiff3 (git tool)
|
||||
4. Firebug (javascript & .css debugging)
|
||||
|
||||
#### Accounts
|
||||
|
||||
1. Git Account
|
||||
- Register yourself as a Git user in the SAP-Git under: https://git.wdf.sap.corp:8080/
|
||||
- Ask the Git administrator (Axel Uhl) to get on the list of enabled committers
|
||||
|
||||
2. Bugzilla
|
||||
- Ask the Bugzilla administrator (Frank Mittag, Axel Uhl) to create a bugzilla account for you.
|
||||
- Bugzilla url: http://sapsailing.com/bugzilla/
|
||||
|
||||
3. Race Analysis user
|
||||
- Add yourself as an user to the Race Analysis suite by adding a Jetty user in the file
|
||||
java\target\configuration\jetty\etc\realm.properties
|
||||
|
||||
#### Steps to build and run the Race Analysis Suite
|
||||
|
||||
1. Get the content of the git repository
|
||||
- Clone the repository to your local file system from `ssh://[SAP-User]@git.wdf.sap.corp:29418/SAPSail/sapsailingcapture.git` or `ssh://[user]@sapsailing.com/home/trac/git`
|
||||
|
||||
2. Check out the 'master' branch from the git repository. The 'master' branch is the main development branch. Please check that you start your work on this branch.
|
||||
|
||||
3. Setup and configure Eclipse
|
||||
- Make absolutely sure to import CodeFormatter.xml (from $GIT_HOME/java) into your Eclipse preferences (Preferences->Java->Code Style->Fortmatter)
|
||||
- Install the Eclipse GWT-Plugin (now called Google Plugin for Eclipse, you need the Gogle WebToolkit SDK from the same update site, too)
|
||||
- Install Eclipse eGit (optional)
|
||||
- Check that JDK 1.7 is available and has been set for compilation in Eclipse
|
||||
- Check that the both JDKs are available (Windows->Preferences->Java->Installed JREs)
|
||||
- Check that JDK 1.6 has been matched to JavaSE-1.6 and that JDK 1.7 has been matched to JavaSE-1.7 (...>Installed JREs>Execution Environments)
|
||||
- It is also possible to match the SAPJVM 6 or 7 to the JavaSE-1.6 (for profiling purposes)
|
||||
- Import all Race Analysis projects from the /java(!!!) subdirectory of the git main folder
|
||||
- Set the Eclipse target platform to race-analysis-p2-ide-local.target (located in com.sap.sailing.targetplatform/definitions)
|
||||
- Wait until the target platform has been resolved completely
|
||||
- In the project com.sap.sailing.gwt.ui create a new subfolder "classes" in the folder WEB-INF
|
||||
- Rebuild all projects
|
||||
|
||||
4. Run the Race Analysis Suite
|
||||
- Start the MongoDB
|
||||
- Start the appropriate Eclipse launch configuration (e.g. 'Sailing Server (Proxy)')
|
||||
- Start the GWT UI
|
||||
|
||||
5. Within the Race Analysis Suite
|
||||
- For TracTrac Events: (Date 27.11.2012) Use Live URI tcp://10.18.22.156:4412, Stored URI tcp://10.18.22.156:4413, JSON URL http://germanmaster.traclive.dk/events/event_20120905_erEuropean/jsonservice.php
|
||||
- Press List Races
|
||||
|
||||
#### Maven Setup
|
||||
Copy the settings.xml from the top-level git folder to your ~/.m2 directory and adjust the proxy settings accordingly. Make sure the mvn executable you installed above is in your path. Open a shell (preferrably a git bash or a cygwin bash), cd to the java/ subfolder of the git workspace and issue "mvn -fae clean install". This should build the software and run all the tests. If you want to avoid the tests being executed, run "mvn -Dmaven.test.skip=true -fae clean install". If you want to make sure the GWT compiler really re-builds all artifacts, remove all java/com.sap.sailing.gwt.ui/com.sap.sailing.gwt.ui.* directories, then re-build.
|
||||
|
||||
#### Further hints
|
||||
- Configure Eclipse to use Chrome or Firefox as the default browser
|
||||
- Install the GWT Browser Plugin (Chrome or Firefox) for the GWT Development mode
|
||||
|
||||
#### Additional steps required for Android projects
|
||||
|
||||
To ensure that all components of the Analysis Suite are working, you should also import all Android projects into your workspace. There are some additional requirements to enable the build process of these projects.
|
||||
|
||||
1. Add the Android Development Tools (ADT) plugin to your Eclipse IDE
|
||||
- In Eclipse click Help -> Install New Software -> Add and enter https://dl-ssl.google.com/android/eclipse/
|
||||
- Select the Developer Tools and install
|
||||
- After restarting Eclipse the "Welcome to Android Development" window should help you with installing the Android SDK
|
||||
- It is also possible to download the Android SDK separately from http://developer.android.com/sdk/index.html ("Use an existing IDE")
|
||||
2. Setup the Android SDK
|
||||
- In Eclipse press Window -> Android SDK Manager
|
||||
- Ensure that everything of "Tools" is installed
|
||||
- Install everything of "Android 3.2 API 13"
|
||||
- Install "Android Support Library" (Extras), "Google Play Services" (Extras) and "Google USB Driver" (Extras)
|
||||
3. Import the Android projects into your workspace
|
||||
- Android projects can be found in the /mobile subdirectory
|
||||
|
||||
To deploy an Android project (for example com.sap.sailing.racecommittee.app) to a real device:
|
||||
|
||||
1. Plug-in the device
|
||||
- Development mode must be enabled on the device
|
||||
- For certain device/OS combinations additional device drivers are needed
|
||||
- You can check if the device is detected correctly by checking the "Devices" tab of the "DDMS" Eclipse perspective.
|
||||
2. Start a run configuration of the project
|
||||
3. Select your attached device in the device selection screen
|
||||
4. The app should be started after deployment
|
||||
|
||||
See [Mobile Development](mobile-development) for further options to run the applications including emulators.
|
||||
+10
-7
@@ -8,18 +8,21 @@
|
||||
|
||||
[[ORC|wiki/planning/ORC]]
|
||||
|
||||
[[ISAF-Internal Projects|wiki/planning/ISAFInternalProjects]]
|
||||
|
||||
[[Advanced Wind Field Analysis|wiki/planning/AdvancedWindFieldAnalysis]]
|
||||
|
||||
[[Support Specific Analysis Scenarios|wiki/planning/AnalysisScenarios]]
|
||||
|
||||
[[Google Earth as Map|wiki/planning/GoogleEarth]]
|
||||
[[Live Audio Streaming Support|wiki/planning/LiveAudioStreaming]]
|
||||
|
||||
[[AirMAX vs. MikroTik|/wiki/planning/AirMAXvsMikroTik]]
|
||||
[[Renewing the Map (Maps v2.0 discontinued) |wiki/planning/GoogleEarth]]
|
||||
|
||||
[[User Management|wiki/planning/usermanagement]]
|
||||
|
||||
[[Usability of the Administration Interface|wiki/planning/usability-of-the-administration-interface]]
|
||||
|
||||
[[Scaling by Server Replication|wiki/planning/scalebyreplication]]
|
||||
[[Advanced Wind Field Analysis|wiki/planning/AdvancedWindFieldAnalysis]]
|
||||
|
||||
[[AirMAX vs. MikroTik|/wiki/planning/AirMAXvsMikroTik]]
|
||||
|
||||
[[Scaling by Server Replication|wiki/planning/scalebyreplication]]
|
||||
|
||||
[[ISAF-Internal Projects|wiki/planning/ISAFInternalProjects]]
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
# Live Audio Streaming
|
||||
|
||||
See also [Bug 1522](http://bugzilla.sapsailing.com/bugzilla/show_bug.cgi?id=1522). We currently have the ManyPlayers Race Viewer that supports this use case. It is based on Flash and requires several additional server-side components. Adding live audio support to the HTML-based SAP Sailing Analytics could simplify the consumption of live audio streams for certain use cases and could ease server administration considerably.
|
||||
@@ -0,0 +1,11 @@
|
||||
# RaceCommittee App
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## Introduction
|
||||
|
||||
## Features
|
||||
|
||||
## Course Designer
|
||||
|
||||
## Etc
|
||||
@@ -0,0 +1,66 @@
|
||||
# Sailing Web-Services API
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
For all service URLs, please note that we use an Apache reverse proxy to map URLs (and in particular the sub-domain) to a particular server instance. So, www.sapsailing.com may end up on a different server instance than tw2013.sapsailing.com or ess40-2013.sapsailing.com. Usually, we hand out a per-event or per-series URL, such as the ones above (except www.sapsailing.com which is the general landing page), and you would only fetch the content for the event you're interested in, even if the server instance has more.
|
||||
|
||||
In all subsequent explanations, you may replace the "www.sapsailing.com" hostname by an according per-event host name to make sure you get to the event you're interested in.
|
||||
|
||||
## Webservice Documentation
|
||||
http://www.sapsailing.com/sailingserver/webservices
|
||||
|
||||
## Regatta Overview
|
||||
|
||||
To get an overview of which regattas a server offers, use
|
||||
|
||||
http://www.sapsailing.com/sailingserver/regattas
|
||||
|
||||
## Single Regatta
|
||||
|
||||
It lists regattas with their name, scoringSystem and boatclass attributes. Using the regatta name as the "name" parameter in the following service:
|
||||
|
||||
http://www.sapsailing.com/sailingserver/regatta?name=ESS+2012+Cardiff+(Extreme40)
|
||||
|
||||
you will obtain a JSON document that has the regatta structure with its series and fleets, the names of the races in the regatta and some overview data for each race including the name, whether it's a so-called "medal race" (usually resulting in double points), whether it's live (isLive), whether we have tracking data for it (isTracked) and the name of the tracked race (trackedRace) which may be null in case isTracked==false. The trackedRace value can be used in other services to obtain more details about the race.
|
||||
|
||||
## Wind Information
|
||||
|
||||
Here is an example of using the wind service, based on the regatta name and the trackedRaceName of the regatta service:
|
||||
|
||||
http://www.sapsailing.com/sailingserver/wind?regattaname=ESS%202012%20Cardiff%20%28Extreme40%29&racename=Cardiff%20Race12&windsource=COMBINED
|
||||
|
||||
Note that there is also a latdeg and lngdev field in the wind fixes in case you want to plot the wind value somewhere on the map. You can also omit the windsource parameter and will get the complete set of wind data for the race where you can also see the different wind source names, such as "EXPEDITION (6)" denoting one of several wind measurement devices, TRACK_BASED_ESTIMATION indicating what we estimate from the boats' courses, and the well-known COMBINED wind source which adds it all up.
|
||||
|
||||
As I mentioned during our call, there are still some legacy services that haven't been used in a while but which may get you started quickly. We can clean this up later to make things more consistent also on our end.
|
||||
|
||||
## Tracked Race
|
||||
|
||||
The service you can use to obtain more details about a particular race, using the above example, works as follows:
|
||||
|
||||
http://www.sapsailing.com/sailingserver/moderator?action=showrace®attaname=ESS%202012%20Cardiff%20%28Extreme40%29&racename=Cardiff%20Race12
|
||||
|
||||
I attach a README that has some bits of documentation on those legacy web services which still should work as described there. Note in particular that this service grants you time-dependent access to a number of key figures for each competitor which may be of interest also for your "hawk eye view," such as all competitors' current speed over ground, distance traveled, rank, gap to leader, estimated time to next mark and whether the competitors has already started / finished that leg. If you don't provide a time point, the current time will be used for the query, usually giving you the data for the end of the race for past races, and the current data for a live race.
|
||||
|
||||
## Waypoint Positions
|
||||
|
||||
To obtain information about the waypoint positions, use
|
||||
|
||||
http://www.sapsailing.com/sailingserver/moderator?action=showwaypoints®attaname=ESS%202012%20Cardiff%20%28Extreme40%29&racename=Cardiff%20Race12
|
||||
|
||||
A race course may use the same point several times, giving you multiple waypoints referring to the same so-called control point. A control point, in turn, can either be a single mark or can be made up of two marks as for the start and finish line or a gate for which the competitors can choose which mark to round. The service emits the GPS positions for each individual mark, grouped by the control point to which they belong, inside the waypoint referencing this control point. The control point names are unique within a course, and you will therefore see equal lat/lng values for the same control point occurring multiple times in the document in case the course uses the same control point in multiple waypoints.
|
||||
|
||||
## GPS Fixes for Boats
|
||||
|
||||
http://www.sapsailing.com/sailingserver/moderator?action=showboatpositions®attaname=ESS%202012%20Cardiff%20%28Extreme40%29&racename=Cardiff%20Race12
|
||||
|
||||
lists all GPS fixes for the boats. If no from/to time points are specified, this will send you a document that contains all GPS fixes for all boats for the entire race. Each fix has the timepoint, latdeg/lngdeg, truebearingdeg (which may better be referred to as a course over ground or COG for short), the speed in knots (knotspeed) and the tack ("STARBOARD" or "PORT", telling from which side the boat has the wind coming which decides, among other things, who has to yield to avoid collisions). The tack may also help you visualizing the boat properly, with the sails on the right side (on starboard for PORT tack and vice versa).
|
||||
|
||||
Please note that the trackedRaceName values (such as "Cardif Race12") usually differ from the race (column) names used in the leaderboards where we rather use short names such as "R12".
|
||||
|
||||
There can be two different types of leaderboards: regatta leaderboards and flexible leaderboards. The leaderboard group document tells you which is which. See the isRegattaLeaderboard attribute in the leaderboard elements. For flexible leaderboards, the leaderboard group document tells the connection between the leaderboards and the tracked races. See
|
||||
|
||||
http://www.sapsailing.com/sailingserver/leaderboardgroup?leaderboardGroupName=Extreme%20Sailing%20Series%202012
|
||||
|
||||
where you can see the tracked race linked to the leaderboard columns with their trackedRaceName. Unfortunately, the regattaName attribute is missing for the flexible leaderboards which you need to get all parameters for the showwind, showboatpositions, showwaypoints and showrace services. I'll add that now and let you know when it's done.
|
||||
|
||||
I recommend to let user navigate the data available starting with the list of leaderboard groups available in the server (http://www.sapsailing.com/sailingserver/leaderboardgroups). From there, you can obtain the structure of all leaderboards in those groups. For regatta leaderboards, the leaderboardgroup service tells the regatta name which you can use in http://www.sapsailing.com/sailingserver/regatta?name=ESS+2012+Cardiff+%28Extreme40%29 and which then tells you the regatta structure and provides the links to the tracked races. For flexible leaderboards, you have the trackedRaceName and (soon) the regattaName attribute available in the leaderboardgroup document which lets you navigate to showboatpositions, showwaypoints, showrace and the wind service.
|
||||
@@ -0,0 +1,41 @@
|
||||
# UI Tests with Selenium
|
||||
|
||||
[[_TOC_]]
|
||||
|
||||
## General
|
||||
|
||||
To validate the web application from the user perspective we use a combination consisting of Selenium and JUnit, which allows us to simulate user interactions via a real browser instance. Therefore we provide a special JUnit-runner as well as different classes in the package _com.sap.sailing.selenium.core_ to execute tests, using the Selenium WebDriver API, and to keep the execution of the tests as flexible as possible at the same time.
|
||||
|
||||
To avoid duplicated and error prone code in test cases, we prefer the usage of the Page Object design pattern when writing automated UI tests. A page object is an object-oriented class that serves as an interface to the UI. The tests then use the methods of the page object class whenever they need to interact with the UI. The benefit is that if the UI changes, the tests themselves don’t need to be changed. Only the code within the page object needs to be changed. Subsequently all changes to support the new UI are located in one place.
|
||||
|
||||
## Selenium Runner
|
||||
|
||||
The Selenium runner is used to execute tests, using the Selenium WebDriver API. The runner takes a XML configuration file, which has to be provided via the system property _selenium.test.environment.configuration_, and runs the tests for each defined browser. The configuration file is needed to define the browsers with which the tests should be executed as well as to provide all the information to Selenium regarding to the web drivers. To avoid unnecessary errors we also provide a documented XML Schema for the configuration file.
|
||||
|
||||
At runtime, the instance of the web driver along with additional information from the configuration is encapsulated by the interface _TestEnvironment_. The Selenium runner provides an instance to the tests by injecting it to fields of the correspondent type, annotated with _Managed_. With the class _AbstractSeleniumTest_ we provide a skeletal implementation for tests, which already has all the necessary annotations applied. Furthermore this class provides a mechanism to automatically capture a screenshot in the case that a test fails.
|
||||
|
||||
## Additional Classes
|
||||
|
||||
Since GWT applications are heavily AJAX driven, one of the challenges in performing UI tests is to be able to tell when the application is in a state you expect. In simple cases you can wait until a loading animation disappears or until a well-known element has changed the state (e.g. visibility). However, since things are usually not that simple, especially in the context of GWT, it is more stable if we are able to tell exactly when an asynchronous request has finished. For this reason we use a counter for pending request which is incremented if an asynchronous callback is created and decremented when the callback completes, regardless of a success or a failure. With this counter a test which triggers a request (which can cause additional request) can wait until the counter reaches 0 again.
|
||||
|
||||
The necessary JavaScript code for the counter is automatically injected in the host page by the provided class _AbstractEntryPoint_. With the class _MarkedAsyncCallback_ we provide an abstract implementation of the _AsyncCallback_ interface for asynchrony requests, which should be marked as pending until they complete using the introduced counter. Since the counter is incremented as soon as an instance is created, _MarkedAsyncCallback_ is an object of single-use. Therefore it is strictly forbidden to create an instance of this class which is never used or which is used multiple times. Otherwise the counter will have an unpredictable value.
|
||||
|
||||
## Page Object Pattern
|
||||
|
||||
Within a web app's UI there are areas that tests interact with. A page object simply models these as objects within the test code and abstracts from the actual structure (DOM) of a website. This reduces the amount of duplicated code and means that if the UI changes, the fix need only be applied in one place.
|
||||
|
||||
Page objects can be thought of as facing in two directions simultaneously. Facing towards the developer of a test, they represent the services offered by a particular page. Facing away from the developer, they should be the only thing that has a deep knowledge of the structure of a page (or part of a page). It's simplest to think of the methods on a page object as offering the "services" that a page offers rather than exposing the details and mechanics of the page.
|
||||
|
||||
Because the developer of a test should think about the services that they're interacting with rather than the implementation, page objects should seldom expose the underlying web driver or elements. To facilitate this, methods on a page object should return other page objects.
|
||||
|
||||
Since we prefer the usage of the Page Object design pattern when writing automated UI tests, we provide a base class _PageObject_ as well as the two specializations _HostPage_ and _PageArea_. The class _HostPage_ represents a GWT entry point which waits for the completion of the GWT bootstrap process before it is initialized. The _PageArea_ is used to represent a component or a specific area on a page, which is useful to improve maintainability for complex websites and reusable parts.
|
||||
|
||||
There is a lot of flexibility in how the page objects may be designed, but there are a few basic rules for getting the desired maintainability of the test code. Page objects themselves should never be make verifications or assertions. This is part of the test and should always be within the test’s code, never in a page object. The page object will contain the representation of the page, and the services the page provides via methods but no code related to what is being tested should be within the page object. There is one, single, verification which can, and should, be within the page object and that is to verify that the page or the area, and possibly critical elements, were loaded correctly. This verification should be done while instantiating the page object.
|
||||
|
||||
To make the development of page objects as simple and easy as possible, we also support a factory for this pattern which helps to remove some boiler-plate code from the page objects by using annotations. We provide the annotations _FindBy_ and _FindBys_ for fields on a page object to specify a mechanism for locating an element or a list of elements. The factory uses the annotations to lazily locate and wait for the element or the element list to appear, by polling the UI on a regular basis, and initializes the field with the element or the list of elements.
|
||||
|
||||
Since we use GWT to build the UI, we also provide a specific mechanism to locate elements by the value of the GWT debug identifier. By convention we use the attribute _selenium-id_ for the debug identifier which is implemented by the class _AbstractEntryPoint_. The class _BySeleniumId_ defines the corresponding mechanism and locates an element or a list of elements by the value of the selenium-id attribute.
|
||||
|
||||
## Writing and Execution of Tests
|
||||
|
||||
**TODO by Riccardo**
|
||||
+52
-46
@@ -6,11 +6,13 @@
|
||||
On this page the decisions, architecture and API's for using smartphones as an additional input channel for Sailing Analytics are documented. Meanwhile, the architecture of this solution is designed to be flexible enough to support other types of input devices in the future, e.g. [Igtimi](http://www.igtimi.com/) trackers.
|
||||
|
||||
## Branches
|
||||
* `cmd-reuse-racelog-for-cmd-tracking`: server side development of using the RaceLog to create a tracking adapter for Commodity Mobile Devices (CMD) such as smartphones
|
||||
* `race-board-admin`: manual UI based entry of mark passings for the time being, while we do not have a detection algorithm
|
||||
* `cmd-android-tracking`: client side development branch for the tracking application, which enhances the existent race committee app
|
||||
* `cmd-android-tracking`: client side development branch for the tracking application, which enhances the existent race committee app, server side development of using the RaceLog to create a tracking adapter for Commodity Mobile Devices (CMD) such as smartphones
|
||||
|
||||
## Communication
|
||||
|
||||
### Channels
|
||||
|
||||
## Communication Channels
|
||||
The current plan is to use up to three channels for communicating:
|
||||
|
||||
1. **Servlets:** Everything that is not directly related to a specific Race (or rather RaceLog) is handled via POST and GET servlets, where the data should be described as JSON. Examples are: Creating a Race, managing Competitors. Ideally, this would on smartphone side however also benefit from the RaceLog-underlying semi-connectedness functionality. _Caveats: replication and persistence!_
|
||||
@@ -19,6 +21,10 @@ The current plan is to use up to three channels for communicating:
|
||||
|
||||
3. **Other:** The actual tracking data (perhaps also additional data: wind etc.) also has to be transferred. On client side we want to reuse the communication mechanism which the RaceLog is built on top of.
|
||||
|
||||
### Communication during creating a race
|
||||
|
||||
|
||||
|
||||
## Server-side Architecture
|
||||
On the server-side, the architecture of smartphone tracking is intended to be open for extension, so that different types of input devices can be used for tracking one race. Currently, some parts are still tightly coupled to smartphone tracking (e.g. `RacingEventService#createTrackedRaceForSmartphoneTracking()`), but these can be refactored to be generic.
|
||||
|
||||
@@ -30,7 +36,7 @@ The reason for using the OSGi service registry is that it enables decentralized
|
||||
Without a tracking provider that implements a mark passing algorithm, we have to identify mark passings on our own in the context of smartphone tracking, for Sailing Analytics to be able to do any analytics at all. While the mid-term goal definitely is to implement such a detection algorithm, as a workaround a UI entry option has been provided, that can be found in the branch `race-board-admin`, in which the mark passings can be set by hand. This can be accessed by clicking the _Administer Race_ button of a race in the leaderboard detail table, which can be found in the leaderboard configuration panel of the admin console.
|
||||
|
||||
## Servlets
|
||||
The servlets are listed in the chronological order that they can be called. First, persistent competitors are needed, so that they can later on be registered for the race (`createPersistentCompetitor`). These can then be listed (`getPersistentCompetitors`). When this is completed, a race in its pre-race phase can be created (`createRace`), which is then also shown in `getRaceLogsInPreRacePhase`. By selecting one of these RaceLogs and sending `RaceLogPersistentCompetitorRegisteredEvent`s, `RaceLogCourseDefinitionChangedEvent`s, the race can then be moved from its pre race phase into the tracking phase by sending the `RaceLogPreRacePhaseEndedEvent` via the race log. From this moment on - given the fact that all necessary information was already included in the RaceLog, tracking data can be added to the race. On the one hand, marks can be pinged (`pingMark`, for which knowledge of the course layout is necessary, which can be accessed through `currentcourse`), on the other hand fixes of competitors can be recorded (`recordFixes`). Pinging the marks is of course only the first step, the plan is to allow the mapping of tracking devices such as smartphones to marks as well as competitors.
|
||||
The servlets are listed in the chronological order that they can be called. First, persistent competitors are needed, so that they can later on be registered for the race (`createPersistentCompetitor`). These can then be listed (`getPersistentCompetitors`). When this is completed, a race in its pre-race phase can be created (`createRace`), which is then also shown in `getRaceLogsInPreRacePhase`. By selecting one of these RaceLogs and sending `RaceLogPersistentCompetitorRegisteredEvent`s and a `RaceLogCourseDefinitionChangedEvent`, the race can then be moved from its pre race phase into the tracking phase by sending the `RaceLogPreRacePhaseEndedEvent` via the race log. From this moment on - given the fact that all necessary information was already included in the RaceLog, tracking data can be added to the race. On the one hand, marks can be pinged (`pingMark`, for which knowledge of the course layout is necessary, which can be accessed through `currentcourse`), on the other hand fixes of competitors can be recorded (`recordFixes`). Pinging the marks is of course only the first step, the plan is to allow the mapping of tracking devices such as smartphones to marks as well as competitors.
|
||||
|
||||
**Remember to set a start time via the race log**, as the race map relies heavily on it (e.g., the course based wind estimation needs a start time, and without any other wind sources a missing start time results in no boats and marks being displayed at all, as the `SailingService#getRaceMapData()` then fails with a no wind exception).
|
||||
|
||||
@@ -72,6 +78,9 @@ To test the servlets manually, in addition to the unit tests, the chrome plugin
|
||||
**Throws**
|
||||
* `400` Invalid JSON in request
|
||||
|
||||
**Comments**
|
||||
* The server choses the id, so this field can be left blank / not supplied
|
||||
|
||||
### `/sailingserver/racelogtracking/getPersistentCompetitors`
|
||||
`PersistentCompetitorsGetServlet`
|
||||
|
||||
@@ -89,44 +98,27 @@ To test the servlets manually, in addition to the unit tests, the chrome plugin
|
||||
* GET request
|
||||
|
||||
**Returns**
|
||||
* `200` body: JSON array of String Triples that act as RaceLog identifiers (leaderboard name, race column name, fleet name)
|
||||
* `200` body: JSON array of RaceGroups
|
||||
|
||||
### `/sailingserver/racelogtracking/createRace`
|
||||
### `/sailingserver/racelogtracking/createRace?leaderboard=<leaderboardName>&raceColumn=<raceColumnName>&fleet=<fleetName>`
|
||||
`CreateRaceLogTrackedRacePostServlet`
|
||||
|
||||
**Expects**
|
||||
* POST request body: JSON with Leaderboard-DTO, RaceColumn-DTO and BoatClass (see CreateRaceLogTrackedRaceJsonSerializer)
|
||||
```
|
||||
{"leaderboard": {
|
||||
"name": "test",
|
||||
"displayName": "test",
|
||||
"discardThresholds": [1,2],
|
||||
"scoringScheme": "LOW_POINT",
|
||||
"courseAreaId": "Kiel"
|
||||
},
|
||||
"raceColumn": {
|
||||
"name": "test",
|
||||
"isMedalRace": false
|
||||
},
|
||||
"boatClass": {
|
||||
"name": "49er",
|
||||
"typicallyStartsUpwind": true
|
||||
}
|
||||
}
|
||||
```
|
||||
* POST request
|
||||
|
||||
**Returns**
|
||||
* `200` RaceLog Identifier Triple JSON
|
||||
* `200` RaceGroup JSON, containing only the Series/Row/Cell structure for the newly created race
|
||||
|
||||
**Throws**
|
||||
* `400` Invalid JSON in request
|
||||
* `409` RaceColumn and RaceLog already exist in Leaderboard
|
||||
* `404` Leaderboard does not exist, RaceColumn does not exist (if the leaderboard is a `RegattaLeaderboard`)
|
||||
* `409` The RaceColumn already is linked to a tracked race`
|
||||
|
||||
**Comments**
|
||||
* If a leaderboard with the supplied does not already exist, a FlexibleLeaderboard is created. Otherwise, the existing Leaderboard is used without raising an error. An existing RaceColumn will raise an error however, as this also means a RaceLog already exists.
|
||||
* The behaviour of the servlet depends on the type of leaderboard with the name `leaderboardName`. If this is a `RegattaLeaderboard`, then the RaceColumn with the name `raceColumnName` has to already exist. If it is a `FlexibleLeaderboard`, the RaceColumn will be created if it does not yet exist.
|
||||
|
||||
### `/smartphone/recordFixes`
|
||||
`RecordFixesPostServlet`
|
||||
|
||||
**Precondition**
|
||||
* race has already been started by sending a `RaceLogPreRacePhaseEndedEvent`
|
||||
|
||||
@@ -153,15 +145,20 @@ To test the servlets manually, in addition to the unit tests, the chrome plugin
|
||||
|
||||
### `/sailingserver/racelogtracking/pingMark?leaderboard=<leaderboardName>&raceColumn=<raceColumnName>&fleet=<fleetName>`
|
||||
`PingMarkPostServlet`
|
||||
|
||||
**Precondition**
|
||||
* race has already been started by sending a `RaceLogPreRacePhaseEndedEvent` and has not been stopped yet
|
||||
|
||||
**Expects**
|
||||
* POST request body: PingMark as JSON
|
||||
```
|
||||
{"unixtime": 2394820480284,
|
||||
"nmea" : "$GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W*6A"
|
||||
}
|
||||
{
|
||||
"markStringId": "Leeward Mark"
|
||||
"gpsFix": {
|
||||
"unixtime": 1375951388465,
|
||||
"nmea": "$GPRMC,084308,A,41.771311,N,86.933174,E,0.0,0.0,080813,0,W*4D"
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Returns**
|
||||
@@ -176,6 +173,7 @@ To test the servlets manually, in addition to the unit tests, the chrome plugin
|
||||
|
||||
**Expects**
|
||||
* GET request
|
||||
* URL Parameters leaderboard, raceColumn and fleet
|
||||
|
||||
**Returns**
|
||||
* `200` body: CourseBase JSON
|
||||
@@ -191,6 +189,8 @@ Includes a `Competitor` as well a `SmartphoneIdentifier`. On the one hand, every
|
||||
### RaceLogPreRacePhaseEndedEvent
|
||||
This does not include any additional data, and merely indicates that the race can be transformed from its pre-race definition state (e.g. waiting for competitors to register, waiting for boat class, waiting for course definition) to an actual race, where no additional competitors can be added, the boat class is fixes, and tracking may begin. This event is picked up by the `RaceLogRaceTracker`, which then creates the actual tracked race from the data in the RaceLog. For successful creation, at least one competitor has to be registered, and a course must have been set through a `RaceLogCourseDefinitionChangedEvent`.
|
||||
|
||||
##Tracking App Use Cases
|
||||
|
||||
|
||||
##Tracking App Architecture
|
||||
|
||||
@@ -208,29 +208,34 @@ Sends the location information to a web service.
|
||||
### `SAP Sailor Tracker Service`
|
||||
Background process for starting, pausing and stopping tracking. Registers all receivers on a pending intent, which is send periodically.
|
||||
|
||||
### `doPostTask`
|
||||
Async task that handles the execution of post requests.
|
||||
### `AsyncJsonPostTask`
|
||||
Async task that handles the execution of post requests with Json content.
|
||||
|
||||
### `doGetTask`
|
||||
Async task that handles the execution of get requests.
|
||||
### `OnlineDataManager`
|
||||
Enables accessing of data from a `DataStore`. Loads data from Servlets using GET-Requests using a `DataLoader`. For an example how to use the `OnlineDataManager` refer to `SelectRaceFragment`, which loads the RaceLogsInPreRacePhase so that the user can select the race he wants to take part in.
|
||||
|
||||
### `DataStore`
|
||||
Interface for the `DataStore` which stores all data that is relevant for the App (managed Races, Competitors, ...)
|
||||
Implementation: `InMemoryDataStore`
|
||||
|
||||
### `DataLoader`
|
||||
`AsyncDataLoader` which does an HTTP GET to a given URL, parses the data (with a `DataParser`) and sends the data to a `DataHandler`.
|
||||
|
||||
### `AppPreferences`
|
||||
Helper Class for accessing the App Preferences specified in settings_view.xml
|
||||
|
||||
### `DataStore`
|
||||
Interface for the DataStore which stores all data that is relevant for the App (managed Races, Competitors, ...)
|
||||
Implementation: InMemoryDataStore
|
||||
|
||||
### `DataLoader`
|
||||
AsyncDataLoader which does an HTTP GET to a given URL, parses the data (with a DataParser) and sends the data to a DataHandler.
|
||||
### `ListFragmentWithDataManager`
|
||||
Base Class, which provides easy access to the data manager for a Fragment, which wants to display the data in a List.
|
||||
Used for example in the `Select*Fragments`.
|
||||
|
||||
## ToDo
|
||||
|
||||
### Server
|
||||
* set fleet when creating race
|
||||
* only one competitor registered, even though multiple RegisteredEvents in RaceLog?
|
||||
* change names of *Events, as they are not events -> also change names of abstract base classes
|
||||
* use extension serializers
|
||||
* exchange auto JSON to BSON conversion in MongoObjectFactory / DomainObjectFactory for something suited for productive use
|
||||
* editing course in the RaceBoardAdmin
|
||||
* persist tracking data (GPSFixStore)
|
||||
* load stored tracked smartphone race (Panel in Admin Console, RaceLogConnector, only present such races with the necessary data in the racelog, and allow user to select whole leaderboard to restore)
|
||||
* mapping devices to marks
|
||||
* generic method for registering listener for NMEA sentence types (e.g. to then process wind) -> move servlet for receiving NMEA out of smartphoneadapter
|
||||
* accepting / removing competitors
|
||||
@@ -241,9 +246,10 @@ AsyncDataLoader which does an HTTP GET to a given URL, parses the data (with a D
|
||||
* security (not everybody can start race, goes hand in hand with user management)
|
||||
* support dynamic mapping of smartphone to competitor -> so that it can change during the race
|
||||
* support other input channels (e.g. Igtimi)
|
||||
* Servlet for getting Competitors for a certain race: Have a look how this is implemented in the serverside-counterpart of the racecommittee-app: /sailingserver/rc/competitors?leaderboard="+raceGroupName+"&raceColumn"+raceColumnName+ "&fleet="+fleetName
|
||||
* only transfer competitor ID for registering etc. instead of whole competitor
|
||||
|
||||
### Android
|
||||
* change format of sent position Data to degrees and minutes
|
||||
* reuse existing course design functionality to create RaceLogCourseDesignChangedEvent before sending RaceLogPreRacePhaseEndedEvent
|
||||
* abstract sending service, so that all POST / GET requests and not only RaceLogEvents can be sent using the semi-connectedness functionality --> just write JSONObjects/Strings directly into the file. The Servlet has to handle deserialization and the client doesn't have to know what type of object it is after having saved it (is this really the case?)
|
||||
* simplify settings
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
# Theses
|
||||
|
||||
## About
|
||||
Theses written about topics concerning SAP Sailing Analytics can be placed here.
|
||||
|
||||
To add a thesis, add and commit the file (ideally `.pdf`) in the folder `doc/theses` on the `master` branch.
|
||||
Then add a link to that file on this page (either locally by editing this [file](/wiki/theses.md), or through the Gollum web interface), which can be expressed as follows in Markdown Syntax:
|
||||
```
|
||||
[title][/doc/theses/<filename>]
|
||||
```
|
||||
Now push your changes to the remote Git repository. It will take some time before the file will actually become available through the wiki (the master branch is periodically synchronized and checked out for this wiki).
|
||||
|
||||
## List of Theses
|
||||
|
||||
* [Server-side Integration of Mobile Devices](/doc/theses/20130210_Teschke_Server-side_Integration_Mobile_Devices.pdf) (Bachelor Thesis, Feb 2013, Fredrik Teschke)
|
||||
Reference in new issue
Block a user