- suppressed README.AServ and started improve aserv.html

README.AServ

-#######################################################################
-#		Alignment Server launch instructions                  #
-#                      10/02/2014, version 4.6                        #
-#######################################################################
-
-Using the alignment server requires an SQL database server.
-We see here, how to use mysql (http://dev.mysql.com/doc/refman)
-there is also built-in support for PostGres.
-
-PORTS USED BY THE ALIGNMENT SERVER
-----------------------------------
-
-The alignment server is a communicating system that communicates through
-TCP sockets which are bound to ports on your machines. We provide here the
-list of default ports and options to change them as well as the necessity
-for the firewalls to open these ports:
-
-    	default	  option  open?
-HTTP	8089	  -H	  Y
-Jade	8888	  -A
-//	1099		  ? (RMI) 
-	7778		  Y (MTP HTTP)
-WSDL	7777	  -W
-JXTA	6666	  -P
-Oyster	1099	  -O	  Y (RMI/Kaon2)
-
-mysql	3306	--dbmsport	No if on the same machine
-
-Both Jade and Oyster/Kaon2 use rmi connection and the default 1099 port.
-Moreover, concerning Oyster, this port must be open to the outside.
-
-MYSQL FOR THE FIRST TIME
-------------------------
-
-$ sudo /usr/local/mysql/bin/mysqld_safe --user=mysql &
-$ /usr/local/mysql/bin/mysqladmin -u root password <mysqlpassword>
-$ /usr/local/mysql/bin/mysqladmin -u root -h localhost password <mysqlpassword>
-$ /usr/local/mysql/bin/mysql -u root -p<mysqlpassword>
-sql> CREATE DATABASE AServDB;
-sql> GRANT ALL PRIVILEGES ON AServDB.* TO adminAServ@localhost IDENTIFIED BY 'aaa345';
-sql> quit
-
-Of course, you are advised to use different user, password and database name. This can be achieved either:
-- by changing values of DBMSBASE, DBMSUSER and DBMSPASS in AlignmentServer and recompiling;
-- by passing parameters dbmsbase, dbmsuser and dbmspass to AlignmentServer.
-
-Sample backup of the server content:
-$ /usr/local/mysql/bin/mysqldump -u adminAServ -paaa345 AServDB > toto.sql
-
-And restoring:
-$ /usr/local/mysql/bin/mysql -u adminAServ -paaa345 AServDB
-sql> source toto.sql;
-
-LAUNCHING MYSQL AND LOADING SAMPLE DATABASE
--------------------------------------------
-
-The next time it is sufficient that mysql is running... (with the database loaded)
-
-$ sudo /usr/local/mysql/bin/mysqld_safe --user=mysql
-
-LAUNCHING THE ALIGNMENT SERVER WITH OYSTER REGISTERY
-----------------------------------------------------
-
-The alignment API is already compiled with Oyster support. However, it is not ready to be launched. The instructions to do so are:
-
-1) get the Oyster2 package from http://ontoware.org/projects/oyster2
-2) copy the four libraries in lib/ (or at least in the classpath)
-3) copy the O2serverfiles directory
-4) copy the "new store" config file
-5) edit the "new store" config file for it to use the correct environent
-6) launch kaon2.jar
-
-java -cp lib/kaon2.jar org.semanticweb.kaon2.server.ServerMain -registry -rmi -ontologies O2serverfiles
-
-[use -registryport for using another port than 1099,
- then the "new store" configuration file must be edited]
-
-7) launch the server
-
-java -jar lib/alignsvc.jar -O -d4
-
-IN CASE OF PERMGEN ERROR
-------------------------
-
-Necessary because we load all classes in the path to check if they implement an interface...
-
-It can be extended by -XX:MaxPermSize=256m
-
-RUNNING THE ALIGNMENT SERVER
-----------------------------
-
-$ java -jar lib/alignsvc.jar -H
-$ java -jar lib/alignsvc.jar -Dwndict=../WordNet-3.0/dict -H
-
-The alignment server is then available through HTTP with:
-
-    	      http://localhost:8089/html/
-
-For debugging, using logback, do:
-$ java -cp lib/slf4j/logback-core-1.0.9.jar:lib/slf4j/logback-classic-1.0.9.jar:lib/alignsvc.jar -Dlogback.configurationFile=logback.xml fr.inrialpes.exmo.align.service.AlignmentService -Dwndict=../WordNet-3.0/dict -H
-
-
-

README.TXT

 #######################################################################
 #              Ontology alignment API and implementation              #
-#                      10/02/2014, version 4.6                        #
+#                      27/05/2014, version 4.6+                        #
 #                  http://alignapi.gforge.inria.fr                    #
 #######################################################################
 
@@ -27,7 +27,7 @@ Read the LICENSE.TXT file for the terms of the LGPL license.
 WHAT IS ONTOLOGY ALIGNMENT?
 ---------------------------
 
-See http://alignapi.gforge.inria.fr for the moment.
+See http://alignapi.gforge.inria.fr.
 See also http://www.ontologymatching.org
 
 USING THE ONTOLOGY ALIGNMENT API IMPLEMENTATION
@@ -37,7 +37,7 @@ Building:
 ---------
 
 $ ant jar
-(or ant compileall; ant jar)
+(or ant compileall)
 
 Testing
 -------
@@ -105,7 +105,6 @@ FILES
 -----
 
 README.TXT	this file
-README.AServ	instructions for setting up an Alignment Server
 LICENSE.TXT	the terms under which the software is licensed to you.
 build.xml	the Ant build file for compiling and testing
 classes/	directory for compiling the sources
@@ -131,3 +130,19 @@ src/		Java sources of ontoalign
 		fr.inrialpes.exmo.ontowrap: Abstract ontology layer
 test/		Unit tests for testng
 tools/		Compile-time tools (testng, etc.)
+
+RUNNING THE ALIGNMENT SERVER
+----------------------------
+
+For information on how to setup an alignment setver, please consult the
+more elaborate documentation at: html/aserv.html
+
+$ java -jar lib/alignsvc.jar -H
+$ java -jar lib/alignsvc.jar -Dwndict=../WordNet-3.0/dict -H
+
+The alignment server is then available through HTTP with:
+
+    	      http://localhost:8089/html/
+
+For debugging, using logback, do:
+$ java -cp lib/slf4j/logback-core-1.0.9.jar:lib/slf4j/logback-classic-1.0.9.jar:lib/alignsvc.jar -Dlogback.configurationFile=logback.xml fr.inrialpes.exmo.align.service.AlignmentService -Dwndict=../WordNet-3.0/dict -H

html/aserv.html

@@ -10,16 +10,16 @@
 <h1 class="titre">Setting up an Alignment Server</h1>
 
 <p>An extensive presentation of the alignment API can be
-  found at <a href="http://gforge.inria.fr/docman/?group_id=117">http://gforge.inria.fr/docman/?group_id=117</a>. We also have
-  an on-line <a href="tutorial/tutorial1/server.html">tutorial</a> on using it.</p>
+  found at <a href="http://alignapi.gforge.inria.fr">http://alignapi.gforge.inria.fr</a>. We also have
+  an on-line <a href="tutorial/tutorial1/server.html">tutorial</a> on
+  using it through the server.</p>
 
 <h2>Requirements</h2>
 
 <p>Using the alignment server requires an SQL database server.
-We see here how to use mysql (http://dev.mysql.com/doc/refman), but
-  the server also works with Postgres.</p>
+We see here how to use <a href="http://dev.mysql.com/doc/refman">mysql</a> or Postgres.</p>
 
-<h2>Creating the MySQL database</h2>
+<h3>Creating the MySQL database</h3>
 
 <p>
 In order to use the Alignment server, it is necessary to create its database. This can simply be done by the following shell instructions:
@@ -45,10 +45,24 @@ database name. This can be achieved either:
 </ul>
 </p>
 
+<h3>Creating the Postgres database</h3>
+
+<p>
+Tentative by JE:
+<div class="terminal">
+$ psql -U postgres
+postgres# CREATE DATABASE AServDB;
+postgres# CREATE USER adminAServ PASSWORD 'aaa345';
+postgres# ALTER DATABASE AServDB OWNER TO adminAServ;
+postgres# quit
+</div>
+Tentative by JD:
+<div class="terminal">
+su postgres
+createuser adminAServ
+createdb -O adminAServ AServDB
+</div>
 <p>
-It is also possible to use Postgres instead of MySQL, but then you
-should know how to do it.
-</p>
 
 <h2>Launching the Alignment server</h2>
 
@@ -70,29 +84,36 @@ The alignment server is then available through HTTP with:
 The possible switches to the server launcher are:
 <div class="terminal">
 $ java -jar lib/alignsvc.jar -h
-options are:
-	--html[=port] -H[port]			Launch HTTP service
-	--jade[=port] -A[port]			Launch Agent service
-	--wsdl[=port] -W[port]			Launch Web service
-	--jxta[=port] -P[port]			Launch P2P service
-	--oyster -O			Register to Oyster directory
-	--serv=class -i class			Launch service corresponding to fully qualified classname
-	--output=filename -o filename	Redirect output to filename
-	--dbmshost=host -m host			Use DBMS host
-	--dbmsport=port -s port			Use DBMS port
-	--dbmsuser=name -u name			Use DBMS user name
-	--dbmspass=pwd -p pwd			Use DBMS password
-	--dbmsbase=name -b name			Use Database name
-	--dbms=name -B name			Use Database Management System
-	--uriprefix=uri -f uri			Set alignment URIs with this prefix
-	-Dparam=value			Set parameter
-	--help -h			Print this message
-
-Alignment server 4.4 (1835M) ($Id$)
+usage: java fr.inrialpes.exmo.align.service.AlignmentService [options]
+            Launch an Alignment server
+
+Options:
+ -A,--jade &lt;PORT>       Launch JADE service (with port PORT; default 8888)
+ -b,--dbmsbase &lt;BASE>   Use DBMS BASE (default: AServDB)
+ -B,--dbms &lt;DBMS>       Use DBMS system (mysql,postgres; default: mysql)
+ -D &lt;NAME=VALUE>        Use value for given property
+ -d,--debug &lt;LEVEL>     debug argument is deprecated, use logging instead
+                        See http://alignapi.gforge.inria.fr/logging.html
+ -H,--http &lt;PORT>       Launch HTTP service (with port PORT; default 8089)
+ -h,--help              Print this page
+ -i,--impl &lt;CLASS>      Launch service corresponding to CLASS
+ -l,--dbmsuser &lt;USER>   Use DBMS USER (default: scott)
+ -m,--dbmshost &lt;HOST>   Use DBMS HOST (default: localhost)
+ -o,--output &lt;FILE>     Send output to FILE
+ -O,--oyster            Register to Oyster directory
+ -P,--params &lt;FILE>     Read parameters from FILE
+ -p,--dbmspass &lt;PASS>   Use DBMS PASSword (default: tiger)
+ -s,--dbmsport &lt;PORT>   Use DBMS PORT (default: null)
+ -S,--host &lt;HOSTNAME>   Set the HOSTNAME of the server
+ -u,--uriprefix &lt;URI>   Set alignment URIs with prefix URI
+ -W,--wsdl &lt;PORT>       Launch Web service (with port PORT; default 7777)
+ -X,--jxta &lt;PORT>       Launch JXTA service (with port PORT; default 6666)
+
+Alignment server 4.6 (1934M)
 </div>
 </p>
 
-<h2>Embedding more methods in the Alignment Server</h2>
+<h3>Embedding more methods in the Alignment Server</h3>
 
 <p>Adding new matcher, renderer, evaluators, or services in the
   Alignment Server, is really easy. This requires that your class be
@@ -113,6 +134,40 @@ is the required MANIFEST file for embedding our OLA algorithm which
 requires two jarfiles: procola.jar and olgraph.jar.
 </p>
 
+<h3>In case of a PermGem error</h3>
+
+<p>
+Because we load all classes in the path to check if they implement an
+API interface, this may raise a PermGem error. The only solution is to
+increase its size with:
+<div class="terminal">
+-XX:MaxPermSize=256m
+</div>
+in the command line.
+</p>
+
+<h3>Launching the server with Oyster registery (legacy)</h3>
+
+<p>
+The alignment API is already compiled with Oyster support. However, it is not ready to be launched. The instructions to do so are:
+<ol>
+<li>get the Oyster2 package from http://ontoware.org/projects/oyster2</li>
+<li>copy the four libraries in lib/ (or at least in the classpath)</li>
+<li>copy the O2serverfiles directory</li>
+<li>copy the "new store" config file</li>
+<li>edit the "new store" config file for it to use the correct environent</li>
+<li>launch kaon2.jar:
+<div class="terminal">
+$ java -cp lib/kaon2.jar org.semanticweb.kaon2.server.ServerMain -registry -rmi -ontologies O2serverfiles
+</div>
+(use -registryport for using another port than 1099,
+ then the "new store" configuration file must be edited)
+</li>
+<li>launch the server:
+<div class="terminal">
+$ java -jar lib/alignsvc.jar -O -d4
+</div></li>
+</ol>
 
 <h2>Ports used by the Alignment Server (by default)</h2>
 
@@ -140,12 +195,29 @@ for the firewalls to open these ports:
 Of course, the ports need only to be open if there is an access from
 the outside to the server with the corresponding plug-in. The only
 compulsory ports for the server is the MySQL one.
+Both Jade and Oyster/Kaon2 use rmi connection and the default 1099 port.
+Moreover, concerning Oyster, this port must be open to the outside.
 </p>
 
-<h2>Setting up a back-up for your database</h2>
 
+<h2>Configuring an Apache frontend</h2>
 
-<p>Sample backup of the server content:
+<p>
+It may be convenient to provide access to a server through an Apache
+server proxy. For that purpose...
+<div class="terminal">
+$ a2dissite default
+$ a2dissite default-ssl
+$ a2enmod proxy
+$ a2enmod proxy-http
+$ service apache2 restart
+</div>
+</p>
+
+<h2>Setting up a back-up for the database</h2>
+
+
+<p>Sample backup of the server content (MySQL):
 <div class="terminal">
 $ /usr/local/mysql/bin/mysqldump -u adminAServ -paaa345 AServDB > toto.sql
 </div>
@@ -154,6 +226,14 @@ And restoring:
 $ /usr/local/mysql/bin/mysql -u adminAServ -paaa345 AServDB
 sql> source toto.sql;
 </div>
+</p>
+<p>
+For Postgres:
+<div class="terminal">
+$ su postgres
+$ dropdb AServDB
+</div>
+
 </p>
 
 <address>