< if you plan on developing for Versus.
You might already have Java installed. Open a command prompt and try typing `java`.
# Talking to the service
We will be using curl to test the service. If you are on Linux or MacOSX you should have it already. Try typing `curl` on the command prompt.
If you are on windows, you can download a build at http://curl.haxx.se/.
If you want a more rich GUI experience most web browsers have extensions that can be used instead.
For example for Chrome you can try [cREST client](https://chrome.google.com/webstore/detail/dev-http-client/aejoelaoggembcahagimdiliamlcdmfm).
We will be using the service available at http://versus.ncsa.illinois.edu:8182/api/v1 as the example but if you are using a different instance
(for example `localhost`) replace accordingly.
Let's go ahead and list methods Extractors available at that location:
```
curl -H "Accept: application/json" http://versus.ncsa.illinois.edu:8182/api/v1/extractors
```
We asked for json. The service actually default to json. But if we go there with the browser we see formatted html. Try requesting html:
```
curl -H "Accept: text/html" http://versus.ncsa.illinois.edu:8182/api/v1/extractors
```
Now let's make it a bit more interesting by submitting a comparison between two files.
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "dataset1=http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png&dataset2=http://isda.ncsa.illinois.edu/drupal/sites/default/files/danland_logo.png&adapter=edu.illinois.ncsa.versus.adapter.impl.BytesAdapter&extractor=edu.illinois.ncsa.versus.extract.impl.MD5Extractor&measure=edu.illinois.ncsa.versus.measure.impl.MD5DistanceMeasure" http://versus.ncsa.illinois.edu:8182/api/v1/comparisons
```
Please pay close attention to the payload of our submission. Take a look in a more readable form:
```
dataset1 = http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png
dataset2 = http://isda.ncsa.illinois.edu/drupal/sites/default/files/danland_logo.png
adapter = edu.illinois.ncsa.versus.adapter.impl.BytesAdapter
extractor = edu.illinois.ncsa.versus.extract.impl.MD5Extractor
measure = edu.illinois.ncsa.versus.measure.impl.MD5DistanceMeasure
```
It's hard to see if you are on the command line, but the call should have returned a long string of characters, for example `f6eda3ee-400e-475a-9703-426811dc4633`.
That's the id of our new comparison. Let use that id to see the status of the comparison:
```
curl http://versus.ncsa.illinois.edu:8182/api/v1/comparisons/f6eda3ee-400e-475a-9703-426811dc4633
```
Should return something like this:
```
{"id":"f6eda3ee-400e-475a-9703-426811dc4633","firstDataset":"http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png","secondDataset":"http://isda.ncsa.illinois.edu/drupal/sites/default/files/danland_logo.png","adapterId":"edu.illinois.ncsa.versus.adapter.impl.BytesAdapter","extractorId":"edu.illinois.ncsa.versus.extract.impl.MD5Extractor","measureId":"edu.illinois.ncsa.versus.measure.impl.MD5DistanceMeasure","value":"0.0","status":"DONE"}
```
For this particular measure a value of 0 means the MD5 hashes did not match, while with 1 they did. Try comparing the same file:
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "dataset1=http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png&dataset2=http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png&adapter=edu.illinois.ncsa.versus.adapter.impl.BytesAdapter&extractor=edu.illinois.ncsa.versus.extract.impl.MD5Extractor&measure=edu.illinois.ncsa.versus.measure.impl.MD5DistanceMeasure" http://versus.ncsa.illinois.edu:8182/api/v1/comparisons
```
Let's try a different set of measures. Something image related like the distance between binned RGB histograms:
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "dataset1=http://www.ncsa.illinois.edu/assets/img/footer_ncsa.png&dataset2=http://isda.ncsa.illinois.edu/drupal/sites/default/files/danland_logo.png&adapter=edu.illinois.ncsa.versus.adapter.impl.BufferedImageAdapter&extractor=edu.illinois.ncsa.versus.extract.impl.PixelHistogramExtractor&measure=edu.illinois.ncsa.versus.measure.impl.HistogramDistanceMeasure" http://versus.ncsa.illinois.edu:8182/api/v1/comparisons
```
Let's switch our attention to indexing. Let's create a new index by specifying what implementations to use.
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "Adapter=edu.illinois.ncsa.versus.adapter.impl.BufferedImageAdapter&Extractor=edu.illinois.ncsa.versus.extract.impl.RGBHistogramExtractor&Measure=edu.illinois.ncsa.versus.measure.impl.KLdivergenceMeasure&Indexer=edu.illinois.ncsa.versus.store.LinearIndexerDisk" http://versus.ncsa.illinois.edu:8182/api/v1/index
```
Let's add a few files to the index:
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "infile=http://www.ncsa.illinois.edu/includes/images/about.jpg" http://versus.ncsa.illinois.edu:8182/api/v1/index/54d55e93-f268-428f-860b-6d80280f76a7/add
```
After adding at least three files we can query by posting to the `/query` endpoint:
```
curl -H "Content-type: application/x-www-form-urlencoded" -X POST -d "infile=http://www.ncsa.illinois.edu/includes/images/about.jpg" http://versus.ncsa.illinois.edu:8182/api/v1/index/54d55e93-f268-428f-860b-6d80280f76a7/query```
# Installing the service
* Download latest build from http://isda.ncsa.illinois.edu/versus/latest/versus-service-0.6.0-SNAPSHOT-bin.zip
* Set paths to data directory the `versus.properites`.
We will be using the default on-disk implementations and specifying the directories where we want to store the data. For example:
```
file.folder=/Users/lmarini/Data/versus/index1.txt
file.indexerfolder=/Users/lmarini/Data/versus/indexer
file.map=/Users/lmarini/Data/versus/map1.txt
file.directory=/Users/lmarini/Data/versus/upload
```
Go into the bin folder and execute the appropriate startup script. There are two optional parameters that can be specified:
1. the port number (defaults to 8080)
2. the url of the master (if not specified the instance will be the master)
For example:
```
> ./startup.sh
> ./startup.sh 8184 http://localhost:8182/api/v1
```
# Source code
Four projects are used in the tutorial:
* versus-core includes the Java API, execution engine and registry
* versus-image includes basic image methods
* versus-census includes methods for indexing
* versus-service includes the RESTful service
You can use command line git or egit from inside Eclipse.
```
git clone https://opensource.ncsa.illinois.edu/stash/scm/vs/versus-core.git
git clone https://opensource.ncsa.illinois.edu/stash/scm/vs/versus-image.git
git clone https://opensource.ncsa.illinois.edu/stash/scm/vs/versus-census.git
git clone https://opensource.ncsa.illinois.edu/stash/scm/vs/versus-service.git
```
# Building the source
All projects use maven. You can use command line maven `mvn` or the m2e Eclipse plugin.
From the command line go into main directory of project where pom.xml is present and type `mvn install`.
This will `package` and then install into your local maven directory (usually under `~/.m2/repository/`). Do this for versus-core, versus-image and versus-census in this order.
For versus service we want to create a war, so in that case we will be running `mvn assembly:assembly`. All builds are avilable under the `/target` directory.
]]>