University of Sheffield NLP GATE development hints Reporting bugs Submitting a patch The user guide Continuous integration

University of Sheffield NLP Bugs, feature requests Use the tracker on SourceForge Give as much detail as possible GATE version, build number, platform, Java version (1.5.0_15, 1.6.0_03, etc.) Steps to reproduce Full stack trace of any exceptions, including "Caused by…" Check whether the bug is already fixed in the latest nightly build

University of Sheffield NLP Patches Use the patches tracker on SourceForge Best format is an svn diff against the latest subversion Save the diff as a file and attach it, don't paste the diff into the bug report. We generally don't accept patches against earlier versions

University of Sheffield NLP Patches (2) GATE must compile and run on Java 5 Not sufficient to set source="1.5" and target="1.5" but compile on Java 6 This doesn't prevent you calling classes/methods that don't exist in 5 Test your patch on Java 5 before submitting

University of Sheffield NLP The User Guide Everything in GATE is (theoretically) documented in the GATE User Guide Every change to the core should be mentioned in the change log User guide is written in LaTeX

University of Sheffield NLP Updating the user guide Lives in subversion userguide/trunk Build requires pdflatex, htlatex (tex4ht package), sed, make, etc. On Windows, use Cygwin Download and put in directory above the.tex files

University of Sheffield NLP Updating the user guide (2) Edit the.tex files Graphics, screenshots, etc. should be.png Check in changes to.tex files, the PDF and HTML are regenerated automatically by…

University of Sheffield NLP Hudson Continuous integration platform Automatically rebuilds GATE and user guide (among others) whenever they change Also does a clean build of GATE every night Nightly builds published at

University of Sheffield NLP Hudson Junit test results available for each build

Running GATE Embedded in Tomcat (or any multithreaded system) Issues and tricks

University of Sheffield NLP Introduction Scenario: Implementing a web service (or other web application) that uses GATE Embedded to process requests. Want to support multiple concurrent requests Long running process - need to be careful to avoid memory leaks, etc. Example used is a plain HttpServlet Principles apply to other frameworks (struts, Spring MVC, Metro/CXF, Grails…)

University of Sheffield NLP Setting up GATE libraries in WEB-INF/lib gate.jar + JARs from lib Usual GATE Embedded requirements: A directory to be "gate.home" Site and user config files Plugins directory Call Gate.init() once (and only once) before using any other GATE APIs

University of Sheffield NLP Initialisation using a ServletContextListener ServletContextListener is registered in web.xml Called when the application starts up public void contextInitialized(ServletContextEvent e) { ServletContext ctx = e.getServletContext(); File gateHome = new File(ctx.getRealPath("/WEB-INF")); Gate.setGateHome(gateHome); File userConfig = new File(ctx.getRealPath("/WEB-INF/user.xml")); Gate.setUserConfigFile(userConfig); // site config is gateHome/gate.xml // plugins dir is gateHome/plugins Gate.init(); } gate.web..example.GateInitListener

University of Sheffield NLP GATE in a multithreaded environment GATE PRs are not thread-safe Due to design of parameter-passing as JavaBean properties Must ensure that a given PR/Controller instance is only used by one thread at a time

University of Sheffield NLP First attempt: one instance per request Naïve approach - create new PRs for each request public void doPost(request, response) { ProcessingResource pr = Factory.createResource(...); try { Document doc = Factory.newDocument(getTextFromRequest(request)); try { // do some stuff } finally { Factory.deleteResource(doc); } finally { Factory.deleteResource(pr); } Many levels of nested try/finally: ugly but necessary to make sure we clean up even when errors occur. You will get very used to these…

University of Sheffield NLP Problems with this approach Guarantees no interference between threads But inefficient, particularly with complex PRs (large gazetteers, etc.) Hidden problem with JAPE: Parsing a JAPE grammar creates and compiles Java classes Once created, classes are never unloaded Even with simple grammars, eventually OutOfMemoryError (PermGen space)

University of Sheffield NLP Second attempt: using ThreadLocals Store the PR/Controller in a thread local variable private ThreadLocal controller = new ThreadLocal () { protected CorpusController initialValue() { return loadController(); } }; private CorpusController loadController() { //... } public void doPost(request, response) { CorpusController c = controller.get(); // do stuff with the controller }

University of Sheffield NLP Better than attempt 1… Only initialise resources once per thread Interacts nicely with typical web server thread pooling But if a thread dies, no way to clean up its controller Possibility of memory leaks

University of Sheffield NLP A solution: object pooling Manage your own pool of Controller instances Take a controller from the pool at the start of a request, return it (in a finally!) at the end Number of instances in the pool determines maximum concurrency level

University of Sheffield NLP Simple example private BlockingQueue pool; public void init() { pool = new LinkedBlockingQueue (); for(int i = 0; i < POOL_SIZE; i++) { pool.add(loadController()); } public void doPost(request, response) { CorpusController c = pool.take(); try { // do stuff } finally { pool.add(c); } public void destroy() { for(CorpusController c : pool) Factory.deleteResource(c); } Blocks if the pool is empty: use poll() if you want to handle empty pool yourself

University of Sheffield NLP Exporting the grunt work - the Spring Framework Spring Framework Handles application startup and shutdown Configure your business objects and connections between them using XML GATE provides helpers to initialise GATE, load saved applications, etc. Built-in support for object pooling Web application framework (Spring MVC) Used by other frameworks (Grails, CXF, …)

University of Sheffield NLP Initialising GATE with Spring <beans xmlns=" xmlns:gate=" <gate:init gate-home="/WEB-INF" plugins-home="/WEB-INF/plugins" site-config-file="/WEB-INF/gate.xml" user-config-file="/WEB-INF/user-gate.xml"> /WEB-INF/plugins/ANNIE

University of Sheffield NLP Loading a saved application <gate:saved-application id="myApp" location="/WEB-INF/application.xgapp" scope="prototype" /> scope="prototype" means create a new instance each time we ask for it Default is singleton - one and only one instance

University of Sheffield NLP Spring servlet example Spring provides HttpRequestHandler interface to manage servlet-type objects with Spring Declare an HttpRequestHandlerServlet in web.xml with the same name as the Spring bean

University of Sheffield NLP Spring servlet example public class MyHandler implements HttpRequestHandler { public void setApplication(CorpusController app) {... } public void handleRequest(request, response) { Document doc = Factory.newDocument(getTextFromRequest(request)); try { // do some stuff with the app } finally { Factory.deleteResource(doc); } Write the handler assuming single- threaded access Will use Spring to handle pooling for us

University of Sheffield NLP Tying it together web.xml org.springframework.web.context.ContextLoaderListener mainHandler org.springframework.web.context.support.HttpRequestHandlerServlet

University of Sheffield NLP Tying it together (2) applicationContext.xml <gate:saved-application id="myApp" location="/WEB-INF/application.xgapp" scope="prototype" /> <bean id="handlerTargetSource" class="org.springframework.aop.target.CommonsPoolTargetSource"> <bean id="mainHandler" class="org.springframework.aop.framework.ProxyFactoryBean">