    == InteGrade middleware RESTful API test web page ==

This package contains a CGI/Perl program that is an example of application of
the InteGrade RESTful API. 

The example of application consists in page that allows a sequence alignment 
using the NCBI's Basic Local alignment search tool (BLAST) running on an 
instance of the InteGrade middleware.

  === Requirements ===

* Apache web server

* Perl interpreter

* Perl's XML::Simple library 
  This library may be installed at Ubuntu using the following apt command:

sudo apt-get install libxml-simple-perl

* the BLAST tool
  This library may be installed at Ubuntu using the following apt command:

sudo apt-get install blast2

* the GenBank's NR database
  This database may be downloaded at ftp://ftp.ncbi.nih.gov/blast/db/FASTA/nr.gz
(~ 4 GB as of Mar-30-2012) 
the database must be gunziped and prepared with the following command:

formatdb -i nr

(formatdb is included in the apt's "blast2" package):

* the InteGrade middleware
  It may be downloaded at http://www.integrade.org.br
read its documentation in order to install it properly.

* the InteGrade's RESTful Web Service
  It may be downloaded at http://www.integrade.org.br
read its documentation in order to install it properly.


  === Configuration ===

* The contents of the "www" folder must be moved into the Apache's www folder, 
for instance:

sudo mv www/* /var/www/

* Similarly, the contents of the "cgi-bin" folder must be moved into the 
Apache's cgi-bin folder, for instance:

sudo mv cgi-bin/* /usr/lib/cgi-bin/

* The NR database and the files produced by the formatdb command must be
moved to the same database path of the "execution.pl" script; the default
value of the variable $DATABASE is:

/usr/local/blastdb/

* The "blast/index.html" file must point to the URI of the scripts, so change
  all the "TestPageServer.com" to the actual hostname.

* In the "execution.pl" script, replace the $INPUT_ADDRESS and $SAMPLE_ADDRESS 
values with the hostname.

* In the "execution.pl" script, replace the $SUBMISSION_ADDRESS values
with the hostname of the InteGrade's Web Service and its correct port.

* In the "results.pl" script, replace the $INPUT_ADDRESS and $DATA_ADDRESS 
values with the hostname.

* In the "results.pl" script, replace the $STATUS_ADDRESS value
with the hostname of the InteGrade's Web Service and its correct port.

* If the Apache's www path is different than "/var/www" then provide the
actual path changing the $DATA_PATH variable in both scripts.


  === Testing ===

* After start the InteGrade and its Web Service, create at the InteGrade a "BLASTX"
application, submitting the "blast2" binary (if you want to do it using the API, 
you may use the Firefox POSTER plugin to submit the XMLs. To encode the blast2 binary
the Linux's "base64" command may be used).

* In the "results.pl" script, replace the $APPLICATION_ID value with the ID of the 
application submitted in the step above.

* Now we may try to run a BLAST experiment: in the test page, paste some FASTA sequences
into the input box, choose an execution type (sequential or parametric), and submit
the query.

* For parametric executions, the FASTA sequences will be split into up to 
$MAX_NUMBER_OF_NODES files, where $MAX_NUMBER_OF_NODES is a variable defined in
the "execution.pl" script.
  WARNING: do not set $MAX_NUMBER_OF_NODES with a value higher than the number of
LRMs registered in the GRM, once in this case the execution might not work.

* Done! The query reports will appear at the "Results" frame as soon as they are finished.
If the execution is parametric, it may appear more than one report.

* The results may be cleaned through the "Clean all results" button. It erases the
files from the data directory as well.


--------------------------------------------------------------------------------
