Apertium scalable service

Introduction

Project Information

This is one of the 9 Google Summer of Code projects accepted for Apertium (see http://socghop.appspot.com/org/home/google/gsoc2009/apertium).

Student: Víctor Manuel Sánchez Cartagena, University of Alicante, Spain

Mentor: Juan Antonio Pérez-Ortiz, from Transducens Group, University of Alicante, Spain.

Introduction

Currently Apertium is a very useful translation platform, and hopefully it will be even more useful in the future, when new language pairs will be added.

But, if another application wants to profit from Apertium power, Apertium needs to be installed on the same machine. Although installing Apertium is not a very difficult task, as linguistic data are frequently updated, the installation should be updated often too. Moreover, communication between an external application and Apertium is not easy to code, because Apertium only reads input text from standard input.

There is another option: to use the simple web service currently located at http://www.apertium.org/, but it has two major problems:

• Its features are quite limited, since it cannot list available language pairs, and only accepts http GET and POST parameters.
• As it starts a new Apertium instance for each request, it consumes a lot of computer resources, making scalability difficult, especially when there is only a single server.

So, the aim of this project is to build an application wrapper for Apertium with a public web service API (both REST and SOAP) that allows third-party programmers to access it from their desktop or web applications, and request the same operations that can be done with a local installation. The key feature of this application is scalability. It is intended to balance high loads by scheduling and prioritizing pending translations according to the server-side resources available. Environments which will be considered can be static, where there is a fixed amount of servers available, or dynamic, as in elastic cloud computing services. When working in dynamic mode, new servers will be automatically added when load rises. The availability of highly scalable web services for Apertium will catalyze the worldwide use and adoption of the platform in lots of translation contexts.

Technical challenges and application features

One of the first challenges to overcome is the design of a easy-to-use API. A difficult API would stop many developers from integrating Apertium into their applications. Therefore, it would be a great idea to study other popular translation APIs. We plan to use both REST and SOAP technologies to give developers as many options as possible. However, the REST web service will not be be totally RESTful, since it will accept translation requests over HTTP POST in order to overcome HTTP GET length limits.

Currently Apertium's scalability is strongly limited by the fact that it cannot run as a daemon, and has to be launched from scratch every time a translation is required. In a web service environment, continuously launching and terminating Apertium processes by the operative system would cause a very strong overhead. In fact, in preliminary experiments I found that, in a common desktop system, processing more than 10 simultaneous translation requests of around 10000 words each makes the system get out of resources when launching an Apertium instance for each request. However, if we spread the requests between a pair of daemons using a queue, the system keeps responding and it takes less time to perform all the translations.

I have made a very simple implementation of an Apertium daemon for testing purposes. It's a quite simple program that launches Apertium and opens a pipe attached to its standard input. Since the pipe is never closed, the Apertium process never dies. Different translation requests are surrounded in the input stream by special XML tags. However, this is not very useful because, sometimes, Apertium does not output short translations until it receives a new request. This happens because information is stored in buffers, and they are only flushed when they are full or the pipeline processes finish (this never happens in daemon mode). Overcoming this problem probably involves changing Apertium core.

But the most difficult challenge is designing a highly scalable and reliable system that distributes the translation requests between Apertium daemons hosted in different servers (probably there will be more than one daemon per server), and starts or shutdowns daemons on demand. A daemon works only with a pair of languages, because changing the languages would imply instantiating pipeline processes with different dictionaries. In addition, in elastic cloud computing environments (where servers are requested and released on demand) we also need to know when to stop using a server or allocating a new one. So, it is necessary to use load balancing features like priority activation, priority queuing, etc.

There are a lot of fast open source load balancing systems, but most of them are highly web application oriented. So, they only implement simple load balancing algorithms, based on the amount of traffic already assigned to each server, server response time, etc. However, we need to take into account a different source of information in order to forward the request to the right server, as the language pairs of the daemons available in each one. And, since most of the time of a request is spent in the Apertium daemon, it will be better to implement a new load balancing system able to deal with our specific requirements.

The Java platform has a good built-in support for priority queues (see http://java.sun.com/javase/6/docs/api/java/util/AbstractQueue.html and its subclasses) and communication between servers (with the RMI protocol), so using it would be a good option. Additionally, there are completely open source Java implementations and the Apache Axis2 web services engine supports both SOAP and REST web services.

Security must be a very important feature of the system. Applications should register to grant reliable access to the API, and connections from unregistered clients will be limited to a fixed amount per IP.

Working plan

Community bonding period: Study queue and load balancing algorithms, and their possible implementations on Java platform. Study RMI, different ways of daemonizing Apertium and Axis2 web services engine.

• Week 1: Implement daemon mode
• Week 2: "
• Week 3: Test Apertium daemon. Check if it is fault-tolerant and as fast as expected.
• Week 4: Define API and implement some methods without load balancing nor on-demand daemon management.

Deliverable #1: Some of the API methods allow to translate with Apertium using a fixed number of daemons and a single computer.

• Week 5: Implement a protocol for communication between servers
• Week 6: Design and implement load balancing and daemon management algorithm.
• Week 7: "
• Week 8: Implement all API methods

Deliverable #2: API fully implemented, dynamic daemon management with fixed number of servers.

• Week 9: Implement dynamic server management for an elastic cloud hosting environment. Amazon EC2 is probably the best option, but Eucalyptus could also be an alternative, as it is open source and its interface is compatible with Amazon EC2.
• Week 10: "
• Week 11: Testing, evaluation and full documentation. Ensure that the API is well-documented and any external developer can easily integrate Apertium into his/her application.
• Week 12: "
• Week 13: Extra time for schedule slips.

Project completed. Final deliverable: Highly scalable web service application working in both dynamic and static environments, with customizable load balancing.

Student skills and experience

Last September, I finished my degree in Computer Engineering at University of Alicante, and now I am studying a postgraduate diploma in Application Development with Java Enterprise Technology. Next November I will start a Doctorate Programme in Computing Applications.

I have some experience in open source projects:

• ANTLArbol is a tool that builds parse trees from an execution of a parser/translator written in Java with the ANTLR tool. It was my degree dissertation and now is used by Compiler Design students in University of Alicante to debug their compilers and translators. More information: http://code.google.com/p/antlrarbol/

• Currently I am working for the Transducens group in University of Alicante, Spain. I am developing an open-source web project related to social translation around Apertium. We plan to release an early prototype in the next weeks. As a result of this work, I have learnt a lot about Apertium design and its limitations, and I have detected the need for having a highly scalable web service around Apertium.

See also

• Apertium going SOA

Development status

1st week

Apertium now works as a daemon. The same instance can process many translation requests, as they are separated by a superblank with a special comment. Null flush option (-z) is implemented in all modules except deformatters and reformatters. So, the daemon outputs the translation as soon as it is available, but deformatter and reformatter are invoked one time each per translation. The overhead of invoking them is quite small and this way we can use the same daemon to translate different format inputs.

Project is split into 2 subprojects:

• ApertiumServerWS is the request router. It processes Web Service requests and sends them via RMI to the right ApertiumServerGSOC instance. It is also the placement controller, telling each ApertiumServerGSOC the language pairs it should work with. If we detect that this module acts as a bottleneck, we can run more than one instance and share the placement algorithm object via Terracotta (http://www.terracotta.org/).

• ApertiumServerGSOC is a set of Apertium daemons running in the same machine. It processes translation requests sent via RMI. The request router also asks each ApertiumServerGSOC for a list of running daemons, and tells them to start or stop some daemons.

At the time of writing ApertiumServerWS can only work with one ApertiumServerGSOC instance, and only allocates one daemon, for the pair es-ca.

2nd week

• Updated API to match Google AJAX Language API (only translation API, not language detection). Implemented batch processing interface too. More information: http://code.google.com/intl/es/apis/ajaxlanguage/documentation/reference.html#_intro_fonje . Added an API method to list language pairs.

• Simple web interface to test JSON parsing.

• Updated communication protocol. Now when an instance of ApertiumServerGSOC starts, it registers with the request router. The request router asks it for supported pairs and updates its list of servers. When the router receives a translation request, sends it to a server that has a daemon for the requested language pair (parameters like server load are not taken into account). If there isn't any server with a suitable daemon, the router asks one server to create a daemon. The protocol is not very useful, since it doesn't work well on high load situations (it is necessary to allocate more daemons for the same pair) or when there are requests of many different language pairs.

• Test with JMeter. 500 sequential translation requests, i.e. a request is sent when the response to the previous one is received. Source text in Spanish, 1884 characters. Translate it to Catalan. Test file is available in SVN, inside ApertiumServerWS project.

Processing each request takes an average of 102ms

If we change ApertiumServerGSOC code , to make it invoke the whole Apertium pipeline for each request, the average time is 901 ms

Of course, this is a special case where all requests are directed to the same daemon. If there were more different languages in the requests than the maximum number of running daemons, daemons would be stopped and started many times, so the difference between some approaches wouldn't be so big. However, having more than one daemon for the same language pair could make the first test even faster.

3rd week

• Tested application with long inputs (about 2 MiB of text).
• Now it is possible to know CPU and memory consumption of each daemon.
• Implemented a proof of concept of null flush in deformatters and reformatters, but this feature hasn't been tested enough yet

4rd week

• Tested null flush in deformatters and reformatters. This feature will be disabled. The fact that flex stores input in memory buffers makes having a reliable implementation very difficult. I'll deal with it in the future if I have enough time.
• Implemented null flush in Constraint Grammar. There have been some difficulties because it reads Unicode input with ICU library, and I/O functions from this library always report EOF when they read a '\0'. Patch submitted and accepted by VISLCG3 project.
• Now all the stable pairs can work as a daemon.

1st deliverable

• JSON API allows translating and listing language pairs.
• All stable pairs are available.
• A daemon is created for each pair (this behavior will change in the future).
• You can launch more than a server, but load balancing algorithm will only take into account the first one.

5th week

• Fixed bug in apertium-interchunk related to null flush. Committed patch.
• Done some load tests, found interesting conclusions:
  • A single daemon consumes all the CPU capacity of a server, at least in computers with 2 o less CPUs.
  • The average translation time of requests processed by the same daemon (if it's the only running daemon in the computer) is smaller than the average time when requests are spread between some daemons in the same computer.
  • There's no reason to run more than one daemon for the same language pair in the same machine. Admission control procedures (not implemented yet) will allow changing daemon priorities.
• Studied some papers about application placement:
  • A Scalable Application Placement Controller for Enterprise Data Centers
  • Dynamic Placement for clustered web applications
  • Utility-based Placement of Dynamic Web Applications with Fairness Goals
  • Concurrent Management of Composite Services According to Response Time SLAs

6th week

• Starting to implement placement system described by A Scalable Application Placement Controller for Enterprise Data Centers.
  • Implemented Ford-Fulkerson algorithm to solve max flow problem.
  • Implemented Bellman-Ford algorithm. A combination of Ford-Fulkerson and Bellman-Ford algorithms can solve minimum cost maximum flow problem.

7th week

• Implemented core of placement system: Placement Controller. Given a set of machines and applications, and which applications are deployed on which machine, the Placement Controller gives a new placement solution that maximizes the amount of satisfied application demand and minimizes the amount of application starts and stops.

8th week

• Implemented the whole system: placement executor, queue scheduler, admission control, etc.
• Started testing

2nd deliverable

• Dynamic daemon management with a fixed number of servers. It is not tested enough and have some important bugs
• JSON API implemented. SOAP and XML-RPC APIs not implemented yet

9th week

• Debug dynamic daemon management.

10th week

• Debug dynamic daemon management and implement more sophisticated version of queue scheduler.

Steps to test the application

In the machine where the request router will run, checkout ApertiumServerRMIInterfaces and ApertiumServerRouter from my branch:

svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerRMIInterfaces
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerRouter

Then install ApertiumServerRMIInterfaces in the local Maven repository:

cd ApertiumServerRMIInterfaces
mvn install

Edit ApertiumServerRouter/src/main/resources/configuration.properties and set the property requestrouter_rmi_host to the name of the host where it will run.Now we are ready to compile ApertiumServerRouter, with:

cd ../ApertiumServerRouter
mvn package

Start rmimregistry, use port 1098, with the command:

rmiregistry 1098

Finally the ApertiumServerRouter war file from "target" directory in your favorite web server.

In the machine(s) where the apertium instances will run, checkout ApertiumServerRMIInterfaces and ApertiumServerSlave from my branch:

svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerRMIInterfaces
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerSlave

Then install ApertiumServerRMIInterfaces in the local Maven repository:

cd ApertiumServerRMIInterfaces
mvn install

Now we are ready to compile ApertiumServerSlave, with:

cd ../ApertiumServerSlave
mvn package

Unzip target/ApertiumServerSlave-1.0-assembled.zip in your preferred installation directory. Install Apertium with the script installApertiumAndPairs.sh Edit conf/configuration.properties and set the property requestrouter_host to the name of the host where ApertiumServerRouter will run. Finally, run the server with the script run-apertium-server.sh. Use as the first parameter the name of the host where ApertiumServerSlave is running.

Now browse index.jsp page of ApertiumServerRouter web application. If something went wrong, you can check the logs at /tmp.

Documentation

API Specification

Introduction

This API is very similar to Google AJAX Language API to make as easy as possible switching to Apertium JSON API. For more information about Google AJAX Language API, see http://code.google.com/intl/en/apis/ajaxlanguage/documentation/reference.html#_intro_fonje .

There are two resources:

http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate

and

http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/listPairs

The first one translates pieces of plain text or html code, and the second one lists the available language pairs.

Both resources admit GET and POST http methods. The value of arguments must be properly escaped (e.g., via the functional equivalent of Javascript's encodeURIComponent() method).

Common arguments and response format

These arguments are all optional and common to both resources:

• key : User's personal API key. Requests from registered users have higher priority.
• callback : Alters the response format, adding a call to a Javascript function. See description below.
• context : If callback parameter is supplied too, adds additional arguments to the function call. See description below.

If nor callback neither context arguments are supplied, this is the JSON object returned by both resources:

{ "responseData" : JSON Object with the requested data , "responseStatus" : Response numeric code , "responseDetails" : Error description }

If callback argument is supplied, a call to a function named by the callback value is returned. For instance, if callback argument's value is foo, this is the JavaScript code returned:

foo({ "responseData" : JSON Object with the requested data , "responseStatus" : Response numeric code , "responseDetails" : Error description })

If both callback and context arguments are supplied, the returned function call has more arguments. If callback's value is foo and context's value is 'bar:

foo('bar',JSON Object with the requested data , Response numeric code , Error description )

listPairs resource

This resource only accepts the common arguments.

The response data returned is an array of language pairs, following this format:

[{"sourceLanguage": source language code ,"targetLanguage": target language code }, ... ]

responseStatus is always 200, that means the request was processed OK, and responseDetails has a null value.

So if we call this resource with no arguments:

curl 'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/listPairs'

we get, for example:

{"responseData":[{"sourceLanguage":"ca","targetLanguage":"oc"},{"sourceLanguage":"en","targetLanguage":"es"}],"responseDetails":null,"responseStatus":200}

translate resource

This resource accepts the common arguments mentioned above, plus the following specific arguments:

• q : Source text or HTML code to be translated. Compulsory argument.
• langpair : Source language code and target language code, separated by '|' character, which is escaped as '%7C'. Compulsory argument.
• format : Source format. text for plain text and html for HTML code. This argument is optional. If this argument is missing it is assumed that source is plain text.

The response data is JSON object following this format:

{ "translatedText" : translated text }

Many different response status codes can be returned. This is the list with all the codes and their meaning:

• 200 : Text has been translated successfully, responseDetails field is null.
• 400 : Bad parameters. A compulsory argument is missing, or there is an argument with wrong format. A more accurate description can be found in responseDetails field.
• 451 : Not supported pair. Apertium can't translate with the requested language pair.
• 452 : Not supported format. The translation engine doesn't recognize the requested format.
• 500 : Unexpected error. An unexpected error happened. Depending on the error, a more accurate description can be found in responseDetails field.
• 552 : Overloaded system. The system is overloaded and can't process the request.

Here is a simple example. Requesting a translation with:

curl 'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate?q=hello%20world&langpair=en%7Ces&callback=foo'

the result is:

foo({"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200})

And if we add the context parameter:

curl 'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate?q=hello%20world&langpair=en%7Ces&callback=foo&context=a'

we get

foo('a',{"translatedText":"hola Mundo"},200,null)

Batch interface

More than one translation can be performed in the same request if we use more than one q argument or more than one langpair. If there is only one q argument and more than one langpair arguments, the same input string is translated with different language pairs. If there is only one langpair argument and more than one q arguments, the different input strings are translated with the same language pair. And if both arguments are supplied more than one time, and they are repeated exactly the same times, the first q is translated with the first langpair, the second q with the second langpair, etc.

The returned JSON changes a bit when using the batch interface. Now the field responseData contains an array of JSON objects, each one with the usual fields: responseData, responseStatus and responseDetails. Note that we have particular values of responseStatus and responseDetails for each translation, but global values too. If all the translation are OK, these values match, but if there is an error in any translation, global values of these fields take the value of the erroneous translation. If there is more than one erroneous translation, global fields take the value of one the the erroneus translations.

These examples show the described behaviour:

curl  'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate?q=hello%20world&q=bye&langpair=en%7Ces'

{"responseData":[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"adiós"},"responseDetails":null,"responseStatus":200}],"responseDetails":null,"responseStatus":200}

curl  'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate?q=hello%20world&langpair=en%7Ces&langpair=en%7Cca&callback=foo'

foo({"responseData":[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"Món d'hola"},"responseDetails":null,"responseStatus":200}],"responseDetails":null,"responseStatus":200})

curl  'http://ApertiumServerInstallationHost/ApertiumServerRouter/resources/translate?q=hello%20world&q=goodbye&langpair=en%7Ces&langpair=en%7Cca&callback=foo&context=bar'

foo('bar',[{"responseData":{"translatedText":"hola Mundo"},"responseDetails":null,"responseStatus":200},
{"responseData":{"translatedText":"adéu"},"responseDetails":null,"responseStatus":200}],200,null)

User manual

System architecture

There are two main applications that make the web service work:

• ApertiumServerRouter: Runs on a JavaEE web container (like Apache Tomcat) and processes the HTTP translation requests. Spreads them between the different translation servers (that have Apertium installed). It also manages the different Apertium daemons running on the translation servers and, under certain circumstances, can start and stop translation servers.

• ApertiumServerSlave : It's a simple Java application that runs on the translation servers. These servers must have Apertium installed. Receives translation requests from ApertiumServerRouter and sends them to the running Apertium instances. Note that the system is designed to run many ApertiumServerSlave instances (one per server) and only one ApertiumServerRouter instance.

Getting it

At the moment, the only way to get the applications is downloading its source code and compiling them. You'll need to download the source code of three projects from the Apertium svn repository. Before executing the following commands, be sure you have Subversion installed.

svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerRMIInterfaces
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerSlave
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/branches/gsoc2009/vitaka/ApertiumServerRouter

To compile the source code you'll need:

• A Java Development Kit compatible with Java version 6. It can be Sun's implementation or any other implementation that follows the specification (see [1]).
• Maven. If you don't have Maven installed, simply download it, unzip it, and be sure that the bin directory is in your PATH.

Once you are sure you have Java JDK and Maven, you can build the applications.

• Build ApertiumServerRMIInterfaces. This project contains the common classes of ApertiumServerSlave and ApertiumServerRouter:

cd ApertiumServerRMIInterfaces
mvn install

• Build ApertiumServerSlave:

cd ApertiumServerSlave
mvn package

The compiled project can be found in target/ApertiumServerSlave-1.0-assembled.zip

• Build ApertiumServerRouter

cd ApertiumServerRouter
mvn package

The compiled project can be found in target/ApertiumServerRouter.war

• If you need the javadoc of any of the projects, from its root directory execute:

mvn javadoc:javadoc

And the javadoc website will be generated in target/site/apidocs

Installing

ApertiumServerSlave

Unzip ApertiumServerSlave-1.0-assembled.zip to the directory where you want to install it. Be sure that the machine has Internet connection, because the installation script will download Apertium from its SVN repository.

Then run the script installApertiumAndPairs.sh with:

./installApertiumAndPairs.sh

or

bash installApertiumAndPairs.sh

By default it will download and install Apertium and all the stable pairs, and install them under /home/youruser/local. You can change these this options with the following parameters:

• -p Installation_prefix : Changes the installation prefix. If you run the script with the options -p /foo/bar it will install executables under /foo/bar/bin, libraries under /foo/bar/lib, etc.
• -l pair1,pair2,pair3... : Installs only the specified language pairs. The list of pairs must be a subset of the list of stable pairs that can be found in Apertium wiki main page. Note that the language order must be the same that the one in main page, although translators in both ways will be installed, e.g. -p en-es will install translators from Spanish to English and from English to Spanish, but -p es-en won't install any translator. There are pairs that only install a translator in one way, see the arrows in Main page.

When installation is complete, you can safely remove apertium directory. ApertiumServerSlave can't work with an existing Apertium installation, because it modifies Apertium modes files to make it run as a daemon.

ApertiumServerRouter

As this application is packaged as a ready-to-deploy war file, there is no need to installation. To run it simply follow the instructions of your Java web container. But before running it, you'll probably need to configure it.

Configuring

ApertiumServerSlave

Application options can be changed by editing INSTALLATION_DIRECTORY/conf/configuration.properties. These are the options that can be changed and their meaning:

• requestrouter_host: Name of the host where ApertiumServerRouter is running. When this application starts, it contacts ApertiumServerRouter to tell that the server is ready to perform translations. This is the only property you'll need to change to make the system work.
• requestrouter_port: Port of requestrouter_host on which rmiregistry is listening. Default value is 1098.
• requestrouter_objectname: Name of the RMI object exported by ApertiumSeverRouter. If you don't modify it inApertiumSeverRouter 's configuration, the default value is OK.
• memoryrate_64bit: It is known that programs generally need more memory in 64-bit operative systems than on 32-bit ones. If the application is running on a 64-bit operative system, its free memory is multiplied by the value of this property. The default value is 0.6087. It is not recommended to change it. See the calibration section to know how to change this value.
• daemon_frozen_time: If an Apertium instance doesn't emit any output during this time (in milliseconds), having received an input, we assume it is frozen. The default value, 20 seconds should be OK. Change it only if the system reports false frozen daemons.
• daemon_check_status_period: Daemon status checking period, in milliseconds. A very low period can cause system overload, so there is no need to change this value.
• apertium_timeout: Maximum time, in milliseconds, Apertium can take to perform a translation. If this time is exceeded, an error is returned to ApertiumServerRouter. Its default value is very high, so timeouts are only reported when there are unexpected errors.
• apertium_max_deformat: Maximum number of simultaneously running Apertium deformatters. To tranlate a text, first it is deformatted launching an instance of the corresponding apertium deformatter (text deformatter or html deformatter), then it is sent to the right daemon, and finally, the daemon result is reformatted launching an instance of the corresponding apertium reformatter. The system's bottleneck is in the daemons, so the default value for this property is 1.
• apertium_max_reformat: Maximum number of simultaneously running Apertium reformatters. The default value is 1.
• apertium_null_mode_suffix: Suffix that all the modes that allow Apertium running as a daemon share. Don't change it.
• apertium_supported_pairs: Comma-separated list of language pairs the system can translate with (because they can work as daemons). In this case the first code is the source language and the second code, the target language. So, we'll have both en-es and es-en. Don't modify this property. Its value is set by the installation script described above.
• apertium_path: Prefix of the directories where Apertium is installed. Don't modify this property. Its value is set by the installation script described above. If you change this value to pint to an existing Apertium installation, it won't work, because the Apertium installatin needs to be made with the provided installation script, that creates new modes files.

ApertiumServerRouter

Editing ApertiumServerRouter properties is a bit more difficult. You'll need to unzip ApertiumServerRouter.war, change the desired configuration properties and zip its content again. Main configuration options are located in file WEB-INF/classes/configuration.properties. These are the options present in this file:

• requestrouter_rmi_host: Name of the host where ApertiumServerRouter will run. This is the only property you'll need to change to make the system work.
• rmi_registry_port: Port on which rmiregistry is listening. Default value is 1098, so you'll need to manually start rmiregistry on port 1098. Remember that rmiregistry must run on the machine where ApertiumServerRouter runs, as well as on machines running ApertiumServerSlave. The difference is that ApertiumServerSlave starts RMIRegistry automatically, but ApertiumServerRouter doesn't, because of the restrictions of running in a Java web container.
• requestrouter_rmi_name: Name of the RMI remote object exported by ApertiumServerRouter. The default value is OK if you don't modify the requestrouter_objectname property of ApertiumServerSlave.
• requestrouter_rmi_port: Port on which RMI remote object exported by ApertiumServerRouter will listen. There is no need to modify it, unless you get an exception saying "port not available".
• admissioncontrol_interval: Period, in milliseconds, of Admission control updating. Admission control is the subsystem that decides whether a request should be accepted or not, depending on system's load. Don't change this value unless you really know what you are doing.
• admissioncontrol_treshold: If system "calculated load" is over this threshold, requests won't be accepted. The default value has been tested and should work OK, but if requests are rejected while the system is not overloaded, try to increase this value.
• admissioncontrol_k: We get "calculated load" by combining real load and "calculated load" in the previous instant: calculated_load = real_load*k+previous_load*(1-k). The default value have been tested and it is not recommended to change it.
• placement_controller_execution_period: Period, in milliseconds, of Placement controller execution. Placement controller decides which language pairs run on each translation server. This is a critic value. Changing it could make the system crash, so it is better to leave the default value.
• server_status_updater_execution_period: Period, in milliseconds, of server status checking. It is recommended to leave the default value.
• scheduler_maxcharacters_in_daemon_queue: If the number of characters of a language pair being translated by a server is lower than this value. a translation request of that language pair is sent to the server.It is recommended to leave the default value.
• scheduler_maxelements_in_daemon_queue: If the number of request of a language pair being translated by a server is lower than this value. a translation request of that language pair is sent to the server.It is recommended to leave the default value.
• scheduler_not_registered_priority_increment: The higher, the less priority unregistered users have.
• scheduler_timeout: Maximum time, in milliseconds, a server can take to perform a translation. If this time is exceeded, an error is returned. Its default value is very high, so timeouts are only reported when there are unexpected errors.
• load_prediction_alpha: It is very similar to admission control k. The predicted load of the different language pairs is calculated by combining the amount (and size) of requests received during a period of time, and the predicted load before this period, so predicted_load = measured_load*alpha+previous_prediceted_load*(1-alpha). Default value has been tested and it is not recommended to change it.
• request_k: Constant CPU cost of processing a request. The CPU cost of a translation request is calculated by adding this value to the number of characters of the request. Don't change it.

Running

Firstly, run ApertiumServerRouter by deploying your re-zipped ApertiumServerRouter.war in your Java web server. For example, in Apache Tomcat, put that file in the directory called webapps.

Then, run ApertiumServerSlave on each of the servers you want to use to perform translations. Use the script run-apertium-server.sh and add a parameter with the name of the host where ApertiumServerSlave runs:

bash run-apertium-server.sh hostname

It will calculate the server's capacity by performing a series of translations and store it in conf/capacity.properties. If you have already run ApertiumServerSlave previously and you don't want to wait for the capacity calculation, add the argument -capacityFromConfigFile. Using this argument capacity is read from conf/capacity.properties and the startup time decreases.

bash run-apertium-server.sh hostname -capacityFromConfigFile

After reading or calculating capacity, it contacts ApertiumServerRouter and starts to receive translation requests. You can tune RMI ports and remote object name by editing run-apertium-server.sh. See javadoc of class com.gsoc.apertium.translationengines.main.Main for more information.

Of course, servers can be stopped (with Ctrl+C) or started at any time.

Dynamic server management: local networks

If you don't want to manually start and stop translation servers, ApertiumServerRouter can do it for you. It will decide to start or stop servers depending on the translation capacity needed by the incoming requests. You'll only have change some configuration properties, and ApertiumServerRouter will connect to the computers of your network where ApertiumServerSlave is installed, and run it when needed.