Requirements:
    So far everything has been tested only on linux (Ubuntu).
    However the only platform-dependent part is the cassandra dev setup scripts (see below),
    which assume bash; they may or may not work under Cygwin...

    Java: JDK (not JRE). I have 1.6.0_24-b07. Java 1.5 may also work, not tested.

    Maven: maven2. I have 2.2.1. Maven 3 may also work, not tested.
        Install maven ubuntu / debian:
            sudo apt-get install maven2

    Eclipse is recommended for development.
        The project files (.classpath, .project, .settings/) are set up for Eclipse Helios SR2.
        You'll also want the M2Eclipse plugin:
            http://m2eclipse.sonatype.org
        Once you've installed M2Eclipse and restarted, you shoud be able to add this project
            using File / Import..., General:Existing Projects into Workspace.
            It will then spend ages downloading maven dependencies but should eventually work.
        For testing, we're using TestNG rather than JUnit (because Tapestry has a bunch of support for it),
            so you may want to install the "TestNG" Eclipse plugin from here, in the same way as for M2Eclipse:
            http://testng.org/doc/eclipse.html

Background reading:
    This project:
        README-user-stories.txt   - User interaction requirements / design.
        README-datastructures.txt - Cassandra data structure design, vote counting algorithms etc.
    Tapestry info / tutorial:
        http://tapestry.apache.org/creating-the-skeleton-application.html
    Cassandra info / tutorial:
        http://wiki.apache.org/cassandra/FrontPage
        http://wiki.apache.org/cassandra/DataModel
        http://www.datastax.com/docs/0.8/index
        http://maxgrinev.com/2010/07/12/do-you-really-need-sql-to-do-it-all-in-cassandra/
    Hector (data access library used to interface to Cassandra):
        https://github.com/rantav/hector/wiki/User-Guide
        https://github.com/rantav/hector/wiki
        - note some info is a little out-of-date and refers to the old Hector APIs before a recent redesign.
    TestNG (Java unit / integration test library):
        http://testng.org/doc/index.html

To setup cassandra (local installation in the repos, for dev, as current user):
    Run this from top dir of repos:
        ./install-cassandra-for-dev.sh      (one-off unless you use 'git clean' as below)
        ./start-cassandra-for-dev.sh     (start or restart; this will stay open and log to console)
    then from a separate console:
        ./initialize-cassandra-schema.sh (one-off after first startup, unless you use 'git clean' as below)

    To exit cassandra, just Ctrl+C to kill it.

    This setup runs a localhost (single node) cluster, keeping its data in the repos in gitignored dirs,
    so you can clean everything easily, e.g. using 'git clean -d -X -f'

    On linux you may also want to do this, as described here - it will still work without this though:
       http://www.datastax.com/docs/0.8/install/installing#installing-jna

       Edit the file /etc/security/limits.conf, adding the following entries for the user or group that runs Cassandra:
          theusername soft memlock unlimited
          theusername hard memlock unlimited

    You can use jconsole (connect to the CassandraDaemon process) to view its JMX management stuff.

To run the cassandra cli (console querying / DDL tool): start cassandra as above, then:
    ./cassandra-cli-for-dev.sh

To run the webapp from the commandline:
    mvn jetty:run
then it will be accessible at:
    http://localhost:8080/policy-auction/

To run within Eclipse:
    I can't get this to work yet! Should be possible with the "Run Jetty Run" plugin:
        Install the "Run Jetty Run" plugin (http://code.google.com/p/run-jetty-run/)
            in eclipse: search for "Jetty" in the Eclipse Marketplace, or use this update site:
                http://run-jetty-run.googlecode.com/svn/trunk/updatesite
        then use Run Configurations, select Jetty Webapp, click New, enter config
    ...I can get it to launch jetty, but it doesn't seem to start the Tapestry servlet context properly:
        accessing http://localhost:8080/<context> only lists the directory for fileserving, doesn't run Tapestry classes.

To run the TestNG unit tests from the commandline:
    ./initialize-cassandra-for-tests.sh
        (one-off unless you use 'git clean' as below, or unless you change conf/cassandra-schema.txt)
    mvn test

To run or debug TestNG unit tests within Eclipse:
    Assuming you have the TestNG plugin installed (see Requirements, above):
    First, run ./initialize-cassandra-for-tests.sh in the top directory.
    Then right-click the test class (e.g. HectorPolicyManagerImplTest) and choose "Run as... / TestNG Test". Or "Debug as...".

Logging:
    The project uses SLF4J, backed by Log4J.
    Some log messages are written to tables in Cassandra when running the webapp.
    Logging and log filtering levels are configured via the file src/main/resources/log4j.properties.
    Logging can be done from any java code in the webapp like this:

        private static final Logger logger = LoggerFactory.getLogger(MyEnclosingClass.class);
        ...
        logger.info("some message");
        logger.error("Disaster", someException);

Intro to java project structure:
    src/main/java:
        Tapestry-related stuff:
            net/retakethe/policyauction/pages
                Each Tapestry page has one class in here (plus a ".tml" template with matching name).
                This class connects together the page template and the data layer.
                The getter/setter methods provide properties that can be reference in the page .tml template.
                There are also handlers for events such as "onActionFrom..." and "onSuccess...".
                The "@Persist" annotation means that field is kept in the session between page shows.

            net/retakethe/policyauction/components
                Tapestry "components" that can be shared between pages.
                The "Layout" one is used for most of the current pages, set up by the 't:type="layout"' in the page .tml.

            net/retakethe/policyauction/entities
                Data objects acted on by Tapestry pages and passed to/from the data layer.

            net/retakethe/policyauction/services
                AppModule - the 'bind' call here is what makes our Cassandra implementation of the 'DAOManager'
                available for injection into fields of cassandra page classes via '@Inject'.

        Data layer stuff:
            net/retakethe/policyauction/data/api
                Abstract interfaces for the data layer.
                This is what the Tapestry pages talk to.
                No dependency on any specific data store implementation here.

            net/retakethe/policyauction/data/impl
                The implementation of the data layer which talks to Cassandra via the Hector library.
                Nothing in Tapestry should need to reference this directly.

    src/main/resources:
        net/retakethe/policyauction/pages
           <pagename>.tml - HTML template corresponding to each Tapestry page.
               (Note you can make Eclipse show them with HTML syntax highlighting by adding "*.tml" to the "Text/XML"
                content type in Preferences / General / Content Types.)
               This has some magic markup ('t:' and 'p:' namespaces, '${<propertyname>}' and '${<prefix>:<name>}' syntax)
               which Tapestry uses to do all the dynamic stuff at render time.
           <pagename>.properties - values for the '${message:<name>}' placeholders on that page.

        net/retakethe/policyauction/components
           HTML template corresponding to each Tapestry component.

    src/main/webapp:
        WEB-INF/web.xml defines servlet config and sets up Tapestry as a servlet filter.

    src/test/java:
        Unit test classes. Not part of the packaged webapp.

        _fixtures:
            Support fixtures for unit tests - for starting test cassandra DB etc.
        net/retakethe ... :
            The actual TestNG unit tests for classes in src/main/java/net/retakethe ...

    src/test/resources:
        Unit test resources, config etc. Not part of the packaged webapp.
        Some are auto-generated by initialize-cassandra-for-tests.sh.