# Hacking WERTi

This document should help you get started with modifying WERTi's internals.

## The File Hierarchy

	werti/
		desc/
		docs/
		metadata/
		src/
		testcases/
		pom.xml
		COPYRIGHT
		INSTALLATION.markdown
		TODO

## The UIMA Descriptor Files

All UIMA descriptor files are located in `desc/`, which has the following
layout:

	desc/
		annotators/
		enhancers/
		operators/
		testers/
		WERTiTypeSystem.xml

The type system, which is global for all WERTi descriptors, is contained in
`WERTiTypeSystem.xml`.

All annotation on web content is performed by the descriptors in `annotators`.
This includes the two sub-categories `taggers` and `relevance`, for tagging and
relevance annotations respectively.

Different client side enhancement anchors are set up using the files in
`enhancers`.

`operators` contains aggregate descriptors to coordinate the work flow between
all other components.

Finally, `testers` are miscellaneous files used for testing. Feel free to add
your own.

## Documentation

The paper documenting the initial work on WERTi can be found in `docs/paper`.
Installation instructions and a readme are in the toplevel directory.

Javadocs and a complete API can be generated by calling the following command:

	mvn javadoc:javadoc

It will appear in `target/site/apidocs`.

## The Source Code

The source code has the following layout:

	src/
		main/
			java/
			resources/
			webapp/
		test/

The `test` directory *would* hold nice JUnit tests, but so far, none exist.
The `main` directory holds the Java sources, the resources WERTi needs to run
(for now, those are just the tagger model files) and all files the webapp needs
to run (WEB-INF/web.xml and logging properties). Anything accessible to the
(server side) application at run time should go in the folder `webapp`. It also
contains the output of GWT-compilations.

## Compiling the Sources

The standard Maven targets will help you. Type `mvn compile` to compile and
`mvn clean` to delete any results of previous compilations. `mvn package`
creates the `.war` file to deploy on a server. It should contain everything,
including a set of model files and all libraries, which will make it incredibly
big.

Typically, you will not want to build the whole .war archive, as it is quite
big (at least 50 MB) and thus takes a while to build. You can instead use the
Maven webapp-plug in to create an 'exploded' archive, viz. the directory
structure and all files without actually packaging it, by issuing the command
`mvn war:exploded`

All compilation results are in the `target` folder.

#### Notes:

- Maven will typically search its repositories for updates and also for online
  sources of the lingpipe toolkit. You should let Maven do that from time to
  time, but for everyday compiles, the `-o` switch will prevent Maven from going
  online, and thus speed up compilation quite a bit.

- Take care to always have the GWT_HOME variable properly set in your current
  environment. This is a bit cumbersome, and we are looking into ways to address
  this issue.

## Testing

Testing WERTi involves running it in GWT hosted mode for debugging of client-side
JavaScript code, and usually analysing the logging output.

### GWT
To test WERTi in hosted mode, you need to be running a Tomcat webserver. The
current `pom.xml` assumes that Tomcat is running on `localhost:8080`, so on
your machine, on port 8080. You can change that in the pom.xml. I will look
into making this a bit easier to adjust.

#### **Important Note:**
You *need* to adjust `WERTi.properties`, too, to inform WERTi about what server
it is running on if you are not deploying it from this port and your local
machine.

### Logging

The logging configuration is in
`src/main/webapp/WEB-INF/classes/log4j.properties`.