Build TIRA ========== Follow these instructions to build TIRA using [Ant](http://ant.apache.org) or [Eclipse](http://www.eclipse.org/downloads/moreinfo/java.php). In the instructions, the term "main directory" refers to the directory which contains this file. Build with Ant -------------- * Make sure you have [Ant](http://ant.apache.org) installed * Go into the main directory * In the command line prompt, type "ant" Build with Eclipse ------------------ * In Eclipse, open dialog "File" > "New" > "Java Project" * Under "Contents", choose "Create project from existing source" * Browse for the TIRA main directory * Click "Finish" Configuring TIRA ================ TIRA is configured using the [JSON](http://www.json.org) file "system-config.json" in the main directory. * Adjust value for "NODE" to reflect the host URL * Adjust number of threads by changing value for "WORKER" Using TIRA ========== A First Start ------------- On a Unix system, run "./startTira.sh" from the main directory. On a Windows system, run "startTira.bat" from the main directory. You are now able to access TIRA via your browser using the URL you adjusted in "Configuring TIRA". You can try out one of the examples (like "/examples/websearch") in order to test if it works fine. An Example: Websearch --------------------- Go to the page of the "/examples/websearch" program. Enter "hello world" into the input field which is labeled "Query". From the drop down list "Results", choose "10" and from the list "Engine" select "CHATNOIR". Now use the "+" button next to "CHATNOIR". It will provide you with a further drop down list from which you have to choose a second search engine. You have now configured the program. It is already prepared to be run. Click "Search". It should display no results yet. Click "Execute" to run the program. It will show you the run configuration below. Now, click "Search" again or select the "Auto Update Result Table" option. You should now also see a "Result" column in the table below the configuration settings. You can click on the link "Result" in order to inspect the results retrieved by one of the search engines. Later, you might wish to find your old results again. You can do so with the "Search" button. Only the results matching the current configuration are displayed. Click the "-" button next to the second engine and then click on "Search" again. Now, only the result of running ChatNoir is displayed. Alternatively, you can search for results from any engine by changing the remaining engine from "CHATNOIR" to "-". If you click again on "Search", all results will be displayed once more. Adding Programs --------------- You can have a look at how the websearch program is used in order to understand how TIRA recognizes and runs programs. It will search recursively in all directories contained in the program root directories (set by "PROGRAMROOT" in the "system-config.java" file). By default this is set to "programs". In "programs/examples/websearch" it finds a file "record.json". Such files are used within TIRA to describe programs. The directory also contains the "websearch.jar" file which contains the Java program. If you open the "record.json" file, you will see that it is indeed a JSON file. It contains four keys: "MAIN", "Query", "Results" and "Engine". The last three ones define the parameters which are displayed on the web page. If the associated value is a string (like for "Query"), an input field will be displayed. Furthermore, the string describes a regular expression of what a valid value is. If the value is a list (like for "Results" and "Engine"), the entries of the list will be items in the corresponding drop down menu. The key "MAIN", however, declares not a option but describes how the program is executed. It contains a string with variables (startin with a "$" symbol). The variables "$Query", "$Results" and "$Engine" will on program start be replaced by the values selected by the user through the web interface. The "$PROGRAM$" variable will then expand to the directory in which the "record.json" lies. Also, you might want to provide the user with some information about your program. To achieve this goal, you can create a "info.html" file in the directory which contains the "record.json". This file should only contain plain text which describes the program and needs no html tag or similar. It's content will then be inserted above the program configuration in the web interface. Finally, please note that currently TIRA has to be restarted in order to detect new programs. Communication with TIRA ----------------------- Programs are always run within an own directory. After running, this directory can be accessed by the "Data Directory" link in the row of the run in the experiments table. However, it is also possible to provide further results to the user. In TIRA7, the standard error output stream is observed by TIRA. Programs can print JSON key-value pairs to this stream which will then show up in the web interface. The format for this is a single line which starts with "{" and ends with "}". Between the brackets, a key-value pair of the form "<key>":"<value>" should be used, where <key> and <value> have to be replaced appropriately. For example, the "websearch" example prints the line '{"Result":"$Run Directory/results.json"}' to standard error. This results in a link within the web interface to the file "results.json" in the run directory. Naturally, also results of experiments are possible. Clearing Experiments -------------------- For each program, a data directory will be created according to the "DATA" setting in the TIRA configuration file. By default, it will create a directory for each program within the "data" directory. Within this directory, a new directory will be created for each run of the program. Thus, you can delete a single run, all runs of a program or simply all runs by deleting the corresponding directories. Note, however, that TIRA has to be restarted to detect these changes. Stopping TIRA ------------- You can stop the TIRA server by typing "q" in the terminal in which it was started and then hitting enter. Questions and Feedback ====================== Email: tim [dot] gollub [aet] uni-weimar.de