tutorial for adding your own metrics
CAUTION: This method only works with v0.91 or later! If you downloaded the code before 13 October 2006, please download it again!
It is assumed that you have downloaded the source code, compiled it, and read through the javadocs. It also might help to download the examples and go through the tutorial on using the built-in datatypes and metrics before attempting to add your own.
The first step in adding your own metric is to create a directory to hold your java files, class files, startup scripts, and data input and output. Please download the entire tarred up directory used for the tutorial, and untar it in the same parent directory as the mobios-v0.91-library dir. Since we will be creating a metric that computes the absolute difference between two integers, our directory is called mobios-v0.91=ab_diff.
$> tar xvzf mobios-v0.91-ab_diff.tar.gz
$> cd mobios-v0.91-ab_diff/
$> ls
This directory or the mobios source code contains every class I will reference in this tutorial. Take a minute to browse through it. (Also, any code that occurs in the mobios source dir is inside the package mobios).
Every metric in the index has an associated datatype that it is defined over. While it's possible to define a new metric over the existing types in mobios.type, since there is no existing type corresponding to integers we'll have to create our own. The general contract of a datatype in the mobios system is that it must implement the IndexObject interface located in mobios.type. So we create MoBIoSInteger.java, implement the necessary methods, and place it in the mobios-v0.91-ab_diff directory. Consult the source code and javadocs for more info on implementing the required methods.
Once we have our datatype, it's easy to define our metric. We just implement the Metric interface located in mobios.dist, and place it in the mobios-v0.91-ab_diff directory. In our implementation this file is called MoBIoSIntegerMetric.java.
Finally, all of our datatypes are dependent upon the class Table for dataloading. So we subclass Table in mobios.db with the class MoBIoSIntegerTable.java.
MoBIoSIntegerTable.java expects a file with a list of integers seperated by newlines. For convenience, we write a simple GenerateIntegers.java class for populating this file. We will use it later to create ints10000.txt, a list of 10000 integers starting at 0.
Finally, we must write code for building and querying the index, since we have introduced a new datatype and metric. The easiest way to do that is to subclass the two sample access class files, BuildVPIndex and QueryVPIndex, located in mobios.app. Thus, in mobios-v0.91-ab_diff, you will find two java files, MyBuildVPIndex and MyQueryVPIndex, that override the necessary methods in BuildVPIndex and QueryVPIndex respectively.
Thus we have written five class files necessary to build and query the index over a new datatype and metric:
MoBIoSInteger.java
MoBIoSIntegerMetric.java
MoBIoSIntegerTable.java
MyBuildVPIndex.java, and
MyQueryVPIndex.java.
We also have a class GenerateIntegers.java, to generate our input file.
It's time to compile the source code. Assuming that you've unpacked mobios-v0.91-ab_diff into the same parent dir as the mobios-v0.9x-library, all you need to do is:
$>javac -cp ../mobios-v0.91-library/build/mobios-v0.91.jar *.java
To test the code, first generate your source file:
$>java GenerateIntegers ints10000.txt 10000
Then to build the index (an explanation of the parameters is available here):
$> java -cp ../mobios-v0.91-library/build/mobios-v0.91.jar:. MyBuildVPIndex -t integer -d ../ -i ints10000.txt -o integer_10000 -s 10000 -b 0
For querying, I just wrote a simple query file and called it query.ints.And to query the index, just call (an explanation of the parameters is available here):
$>java -cp ../mobios-v0.91-library/build/mobios-v0.91.jar:. MyQueryVPIndex -d ../ -i integer_10000 -q query.ints -o query.ints.res -r 4
In this example, the output is saved to query.ints.res.
Enjoy!
For any questions or problems, please email mobios AT mobios.csres.utexas.edu.
