Danno / Dannotate Developer Notes

JUnit tests

WARNING: The unit tests start by erasing the contents of the test triplestores. Do not run them against a production database.

The unit tests for Danno are in the test tree. The easy way to run the unit tests is to select the 'danno' project in Eclipse and use the context menu to run "Run As>JUnit Test". You can also run the tests using the Maven "test" goal.

Danno test applications

WARNING: The test applications start by erasing the contents of the triplestore of the Danno test installation. Do not run them against a production Danno installation.

There are three test "applications" that run against a deployed Danno installation. These should be launched using "Run As>Java Application"

au.edu.diasb.annotation.danno.test.DannoStressTest
This runs some Annotea requests a number of time and displays timing information. Change the relevant server configurations to select between benchmarking RDB, SDB or Sesame.
au.edu.diasb.annotation.danno.test.DannoOAITest
This will run some OAI functional tests.
au.edu.diasb.annotation.danno.test.DannoBenchmark
This simply runs the Stress and OAI tests a number of times, and reports the time taken for each cycle.

The test applications recognize the following command-line options:

--noauth
Do not attempt to authenticate with the Danno server before starting the tests.
--debug
Enable DEBUG logging.
--count <count>
Set each test's record count. Note that for some subtests, the "work load" is proportional to square of the record count. The default value is 100.
--cycle <cycle>
Set the number of cycles to perform in the benchmark. The default value is 3.
--threads <count>
The Stress tests can be performed with multiple client-side threads using this option. The default value is 1.

Danno interoperability testing

While we recommend Dannotate as the tool for creating annotations, Danno should also be interoperable with other annotation tools that implement the Annotea protocol. The Annozilla extension for FireFox is a good example.

The following procedure can be used to test Danno interoperability with Annozilla.

  1. Install Annozilla 0.7.0.a.6 (or later) on your Firefox browser:
    • Go to http://annozilla.mozdev.org/ReleaseNote.html
    • Click on the 3 'xpi' links in turn.
    • Take a few minutes to review the Annozilla draft manual. (It is not entirely up to date and accurate, but it should give you a feel.)
  2. Configure Annozilla to use your Danno server's annotea service:
    • In the Firefox "View>Sidebar" pulldown menu, check the Annozilla box.
    • In the Annozilla sidebar, select "Annozilla>Options".
    • In the Options window, select the "Server Options" pane.
    • Click the "Remote Server" radio button, and enter the URL for your Danno Annotea service; e.g. http://localhost:8080/danno/annotea.
    • Close the Options window.
  3. Use Annozilla to create and view annotations.
    • Open the Annozilla sidebar.
    • Visit some web page you want to annotate.
    • Select some text in the page and use the context menu (right button) to "Annotate Current Selection".
    • In the Annotation window, set a title, add some annotation text and click on Save.
    • The webpage selection that you annotated should now be decorated by Annozilla, and a new annotation should have appeared in the sidebar.
    • Most important, the annotation should have been stored in your Danno annotea services. You should be able to confirm this by using the sidebar's "Annotations>Load from server" function.

Test environment

Unit test triplestore configuration

The unit tests that exercise Jena/RDB and Jena/SDB functionality require a MySQL database backend. The following configuration details are assumed by default:

  • MySQL host = "localhost"
  • MySQL database name = "test" (SDB) or "testrdb" (RDB)
  • MySQL user name = "root"
  • MySQL password = "root"

For details on how to set up and configure a MySQL database installation, please refer to your Linux distro's documentation and/or the MySQL documentation on the MySQL website.

For Sesame unit tests, the triple store is created in the "/tmp/sesame" directory. For Jena/TDB, the "/tmp/tdb" directory is used. Note: these directories need to be created by hand!

You can override these settings by creating a "test.properties" file in the root of your Eclipse workspace, and adding property overrides to that file as required.

Clearing test triplestores

If you need to clear the test triplestore by hand, do one of the following:

  • For RDB/SDB - connect to the relevant database using the "mysql" utility. Either drop and recreate the database, or drop all tables in the database.
  • For TDB - delete the contents of "/tmp/tdb".
  • For Sesame - delete the contents of "/tmp/sesame".

Setting up a local Shibboleth IdP and SP for testing

The procedure for doing this is described in the Test Shibboleth IdP Setup HOWTO. This covers setting up the Identity Provider (IdP) on a remote machine, and the infrastructure for a local Service Provider (SP).

We are currently taking the route of implementing the SP for Danno using the "mod_shib" module for Apache and the associated "shibd" daemon which handles interactions with the IdP. (We are not entirely happy with this as it is not a pure Java solution, and is fraught with deployment issues. But the only alternative for us would be to reimplement the mod_shib / shibd functionality from scratch in Java, and that is not feasible given our project's timeframe.)

Depending on how you configure it, mod_shib can provides mandatory or optional authorization and mandatory or optional access control for parts of the Apache server's webspace. Our goal is to support a hybrid scheme that combines Shibboleth, OpenId and local authentication with local authorization and fine-grained access control, all under the control of SpringSecurity. In order to do this, mod_shib and shibd need to implement shibboleth sessions and shibboleth login and logout, but initiation of session creation (login) and all access control decisions need to be handled in the Danno servlet(s). Accordingly, we use the following "mod_shib" configuration settings for the Danno webspace:

    <Location /dannodemo>
      AuthType shibboleth
      ShibRequestSetting requireSession 0
      ShibUseHeaders On
      require shibboleth
    </Location>

We also configure the Apache reverse proxy configuration to use AJP; e.g.

    ProxyPreserveHost on

    ProxyPass /dannodemo/ ajp://localhost:8009/dannodemo/
    ProxyPassReverse /dannodemo/ ajp://localhost:8009/dannodemo/

(I'm not entirely sure that this is necessary, but the Shibboleth 2 installation instructions say to use AJP.)