Maven Archetype

If you're starting from scratch or if you don't use Java as programming language in your project, the RRE Maven Archetype will create a project template already set up with all what you need to run an evaluation suite.

The RRE Maven archetype generates a Maven project skeleton with all required folders and configuration. In each folder there’s a README and a sample content. The skeleton can be used as a basis for your Java project and it can be used as it is, just for running the quality evaluation (in this case your main project could live somewhere else and could have nothing to do with Java).

Prerequisites

• Java 8 or later
• Apache Maven 3.x

The items above are required in any case, even if you're not using Java as programming language. RRE is written in Java, so if you want to execute it, Java (and Apache Maven as well) is a must.

Step 1: configure the repository

The RRE Maven archetypes are not hosted in the central repository, so we need to configure Maven in order to proper locate the required artifacts. This is done in a file called settings.xml located under the $HOME/.m2 folder. If the file doesn't exist you must create it. Add the following content to the settings.xml file:

<settings>
    <profiles>
      <profile>
           <id>sease</id>
           <repositories>
		 <repository>
			 <id>archetype</id>
			 <name>Sease repository</name>
			 <url>https://raw.github.com/SeaseLtd/rated-ranking-evaluator/mvn-repo</url>
			 <snapshots>
				 <enabled>true</enabled>
				 <updatePolicy>always</updatePolicy>
			 </snapshots>
		 </repository>
	   </repositories>
      </profile>
    </profiles>
</settings>

Step 2: generate the project

Open a command line and go to the directory where you want to host the project. Then, execute the following command:

Apache Solr (Embedded)

Apache Solr will run in an embedded mode. RRE will take care about the entire Solr lifecycle (e.g. start, load, query, stop).

mvn archetype:generate \
-Psease \
-B \
-DarchetypeGroupId=io.sease \
-DarchetypeArtifactId=rre-maven-solr-archetype \
-DarchetypeVersion=1.0 \
-DgroupId=com.yourcompany.whatever \
-DartifactId=solr-project-example \
-Dversion=1.0 \
-DsolrVersion=7.7.2

Where:

• groupId: it is the Maven group identifier of your project
• artifactId: it is the Maven artifact identifier of your project
• version: it is the version you want to assign to your project
• solrVersion: as the name suggests, this is the target Solr version

At the end of the creation process, you will find the following structure:

Apache Solr (External)

In this context, an external instance of Apache Solr is supposed to be up and running somewhere. RRE will only query that instance without any further interaction (e.g. load, start, stop).

mvn archetype:generate \
-Psease \
-B \
-DarchetypeGroupId=io.sease \
-DarchetypeArtifactId=rre-maven-external-solr-archetype \
-DarchetypeVersion=1.0 \
-DgroupId=com.yourcompany.whatever \
-DartifactId=solr-project-example \
-Dversion=1.0 \
-DsolrVersion=7.7.2

Where:

• groupId: it is the Maven group identifier of your project
• artifactId: it is the Maven artifact identifier of your project
• version: it is the version you want to assign to your project
• solrVersion: as the name suggests, this is the target Solr version

Elasticsearch (Embedded)

mvn archetype:generate \
-Psease \
-B \
-DarchetypeGroupId=io.sease \
-DarchetypeArtifactId=rre-maven-elasticsearch-archetype \
-DarchetypeVersion=1.0 \
-DgroupId=com.yourcompany.whatever \
-DartifactId=elasticsearch-project-example \
-Dversion=1.0 \
-DesVersion=6.3.2

Where:

• groupId: it is the Maven group identifier of your project
• artifactId: it is the Maven artifact identifier of your project
• version: it is the version you want to assign to your project
• esVersion: this is the target Elasticsearch version

At the end of the creation process, you will find the following structure:

Elasticsearch (External)

mvn archetype:generate \
-Psease \
-B \
-DarchetypeGroupId=io.sease \
-DarchetypeArtifactId=rre-maven-external-elasticsearch-archetype \
-DarchetypeVersion=1.0 \
-DgroupId=com.yourcompany.whatever \
-DartifactId=elasticsearch-project-example \
-Dversion=1.0 \
-DesVersion=6.3.2

Where:

• groupId: it is the Maven group identifier of your project
• artifactId: it is the Maven artifact identifier of your project
• version: it is the version you want to assign to your project
• esVersion: this is the target Elasticsearch version

Generic search API

mvn archetype:generate \
-Psease \
-B \
-DarchetypeGroupId=io.sease \
-DarchetypeArtifactId=rre-maven-generic-search-archetype \
-DarchetypeVersion=1.1 \
-DgroupId=com.yourcompany.whatever \
-DartifactId=generic-search-project-example \
-Dversion=1.0

Where:

• groupId: it is the Maven group identifier of your project
• artifactId: it is the Maven artifact identifier of your project
• version: it is the version you want to assign to your project

Note that this archetype was introduced in version 1.1 of the project - it is not available in 1.0.

The generic search archetype has marked placeholders in the pom.xml for you to fill in additional details, such as the details of your SearchPlatform implementation. Unlike the Solr and Elasticsearch archetypes, it will not work "out of the box" without these details being supplied.

Regardless the target search platform you've used, at this point you have a project which is properly configured in terms of folders structure and plugin configuration (see the generated pom.xml). Under each folder you will find a sample content (which strongly depends on the target platform) and a README file.

Step 3: run the evaluation process with sample data

Open a shell in the project directory (i.e. the directory which contains the pom.xml file) and run one of the following command:

> mvn clean install

The RRE Maven plugin and RRE Maven reporting plugin will execute. After the build, under the target folder you will find:

• rre/evaluation.json: the evaluation process result, the main RRE output
• site/rre-report.xlsx: the evaluation data in a spreadsheet format.

You can also run the evaluation and the reporting as separate tasks:

> mvn rre:evaluate

> mvn rre-report:report

Note that the pom.xml of the generated project contains another commented output format, which is the RRE Server bind:

<configuration>
    <formats>
      <param>spreadsheet</param>
      <!-- 
           IMPORTANT: uncomment the following line 
           if you're running the RRE server -->
      <!--
          <param>rre-server</param>
       -->
    </formats>
</configuration>

The line above should be uncommented if you are using the RRE Server.

Step 4: replace the sample data

It's time to replace the dummy data provided with the example. In order to do that, other than looking at the sample content, please have a look here where each thing we need to provide to RRE is explained in details.