Installation and developer guide for the MIKM...

DEFENCE DÉFENSE&

Defence R&D Canada – Atlantic

Copy No. _____

Defence Research andDevelopment Canada

Recherche et développementpour la défense Canada

Installation and developer guide for the MIKM

consistency application

Marie-Odette St-HilaireMichel MayrandOODA Technologies Inc.

Prepared by:OODA Technologies Inc.4891 Av. GrosvenorMontreal, QC H3W 2M2

Project Manager: Anthony W. Isenor, 902-426-3100 ext. 106Contract Number: W7707-098207Contract Scientific Authority: Anthony W. Isenor, 902-426-3100 ext. 106

Contract Report

DRDC Atlantic CR 2010-057

July 2010

The scientific or technical validity of this Contract Report is entirely the responsibility of the contractor and the contents do not necessarily have the approval or endorsement of Defence R&D Canada.

This page intentionally left blank.

Installation and developer guide for the MIKMconsistency application

Marie-Odette St-HilaireMichel Mayrand

Prepared by:

OODA Technologies Inc.4891 Av. Grosvenor, Montreal Qc, H3W 2M2

Project Manager: Anthony W. Isenor 902-426-3100 Ext. 106Contract Number: W7707-098-207Contract Scientific Authority: Anthony W. Isenor 902-426-3100 Ext. 106

The scientific or technical validity of this Contract Report is entirely the responsibility of the contractorand the contents do not necessarily have the approval or endorsement of Defence R&D Canada.

Defence R&D Canada – AtlanticContract ReportDRDC Atlantic CR 2010-057July 2010

Principal Author

Marie-Odette St-Hilaire

Approved by

Francine DesharnaisHead/Maritimes Information and Combat Systems Section

Approved for release by

Calvin HyattHead/Document Review Panel

c© Her Majesty the Queen in Right of Canada as represented by the Minister of NationalDefence, 2010

c© Sa Majeste la Reine (en droit du Canada), telle que representee par le ministre de laDefense nationale, 2010

Original signed by Marie-Odette St-Hilaire

Original signed by Francine Desharnais

Original signed by Ron Kuwahara for

Abstract

A service oriented architecture is used to construct a set of web services that interface toapplications previously created by the Maritime Information and Knowledge Managementgroup at DRDC Atlantic. The services link the Automated Ship Image Acquisition System(ASIA) and the SeaSpider application. This report describes the installation procedure forthe developed software. The report covers software prerequisites such as the database man-agement system, java, and Google Earth plugins. The installation of the databases, Tomcat,the web service clients, and the consistency application are also described. The proceduresfor developing a new data service, adding a new data source, or changing the authoritativesource are also documented.

Resume

Une architecture axee sur le service est utilisee pour le developpement d’un ensemble deservices Web qui se connectent a des applications existantes creees par le groupe de gestionde l’information et du savoir maritimes (GISM) a RDDC Atlantique. Ces services lient lesysteme d’acquisition automatisee d’images de navires (ASIA) a l’application SeaSpider.Le rapport decrit la procedure d’installation du logiciel developpe, y compris les exigenceslogicielles prealables : plugiciels de systeme de gestion de base de donnees, Java et GoogleEarth. L’installation des bases de donnees, de Tomcat, des clients de services Web et del’application de verification de la coherence est aussi decrite, tout comme les proceduresde developpement d’un nouveau service de donnees, d’ajout d’une source de donnees oude modification de la source faisant autorite.

DRDC Atlantic CR 2010-057 i


ii DRDC Atlantic CR 2010-057

Executive summary


Marie-Odette St-Hilaire, Michel Mayrand; DRDC Atlantic CR 2010-057; DefenceR&D Canada – Atlantic; July 2010.

Background: The collection of data and information to support Maritime domain aware-ness (MDA) can take on many forms. In the Maritime Information and Knowledge Man-agement group at DRDC Atlantic, the Automated Ship Image Acquisition System (ASIA)acquires photographs of ships as they transit the narrows of Halifax Harbour. The Sea-Spider application supports MDA via the accumulation of web-based information on shiproutes. A cross-comparison of the information available from the two data sources enablesan assessment of the information consistency.

Results: The software known as the consistency application was constructed under con-tract by OODA Technologies over a period of seven months, in support of the AppliedResearch Project 11HL Technologies for Trusted Maritime Situational Awareness. The in-stallation of the developed software is described in this document. The software was builtfollowing the service oriented architecture paradigm and thus relies on many other opensource developments.

Significance: The installation guide provides clear description of how to setup the consis-tency application. The consistency application itself, allows a researcher to cross comparethe information from multiple data sources and generate a comparison score for the indi-vidual ship information and also for the data sources as a unit. Such a score allows theresearcher to assess the capability of the data source to provide meaningful information forMDA purposes. This will allow the identification of those sources that provide the mostreliable information for MDA purposes.

Future Plans: The intent is to include additional data sources in the consistency applica-tion. This will increase the data available for cross comparison. In turn, this will increasethe likelihood of identifying poor data and poor data sources.

DRDC Atlantic CR 2010-057 iii

Sommaire


Marie-Odette St-Hilaire, Michel Mayrand ; DRDC Atlantic CR 2010-057 ; R & Dpour la defense Canada – Atlantique ; juillet 2010.

Contexte : La collecte de donnees et de renseignements en appui a la connaissance dela situation maritime (CSM) prend de nombreuses formes. Au sein du groupe de ges-tion de l’information et du savoir maritimes (GISM), le systeme d’acquisition automatiseed’images de navires (ASIA) prend des photos des navires qui franchissent le passage duport d’Halifax. L’application SeaSpider appuie la CSM en accumulant des renseignementsWeb sur les itineraires des navires. La comparaison des renseignements disponibles dansles deux sources de donnees permet d’evaluer la coherence de l’information.

Resultats : Le logiciel connu sous le nom d’application de verification de la coherencea ete developpe dans le cadre d’un contrat de sept mois accorde a OODA Technologiesen appui au projet de recherche appliquee 11HL : Technologies assurant la fiabilite de laconnaissance de la situation maritime. Le document decrit l’installation de ce logiciel. Ledeveloppement du logiciel etait fonde sur un cadre conceptuel d’architecture axee sur leservice et s’appuyait donc sur plusieurs autres projets de developpement de code sourcelibre.

Importance : Le guide d’installation fournit une description claire des etapes de confi-guration de l’application de verification de la coherence. Celle-ci permet aux chercheursde comparer les renseignements provenant de multiples sources de donnees et de genererune cote de comparaison pour les renseignements sur chaque navire et pour les sourcesde donnees elles-memes. Une telle cote permet aux chercheurs d’evaluer la capacite d’unesource de donnees a fournir des renseignements pertinents aux objectifs de la CSM, ce quipermet de determiner les sources qui fournissent les renseignements les plus fiables.

Perspectives : Nous prevoyons ajouter d’autres sources de donnees a l’application deverification de la coherence. La quantite de donnees susceptibles d’etre comparees seraainsi accrue. Par consequent, il sera plus facile de cerner les mauvaises donnees et lessources de donnees non fiables.

iv DRDC Atlantic CR 2010-057

Table of contents

Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i

Resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i

Executive summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii

Sommaire . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv

Table of contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

List of figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

1 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 Document Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Quick Installation Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.1 Java and WinAnt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.3 Set the Data Source Name . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.4 Firefox and Google Earth Application programming interface (API) . . . . 5

3 Database Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.1 Database Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2 ITU Database Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.3 Enabling Remote Access to MySQL Server . . . . . . . . . . . . . . . . . 6

3.4 Extra Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 Tomcat Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.1 Tomcat-jUDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

4.2 Tomcat Without jUDDI . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4.2.1 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

DRDC Atlantic CR 2010-057 v

4.2.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4.3 Axis2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5 Web Services Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.1 Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.2 Deployment on Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

6 Consistency Application (CA) Configuration and Execution . . . . . . . . . . . . 13

6.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.2 Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6.3 Running the CA at the Command Line . . . . . . . . . . . . . . . . . . . 14

6.4 Running the CA Using Eclipse . . . . . . . . . . . . . . . . . . . . . . . 15

7 CA Client Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

8 Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

8.1 Eclipse Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

8.2 Eclipse Axis2 Plugins Installation . . . . . . . . . . . . . . . . . . . . . . 17

8.3 Creating Eclipse Projects from Java Code . . . . . . . . . . . . . . . . . . 18

8.3.1 caClientWS Project . . . . . . . . . . . . . . . . . . . . . . . . . 20

8.4 Data Service Development Using Eclipse Axis2 Plugins . . . . . . . . . . 21

8.4.1 Bottom-Up Development . . . . . . . . . . . . . . . . . . . . . . 21

8.4.2 Archiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.4.3 WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

8.4.4 Client Stub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8.4.5 Data Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.5 Publishing Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

8.6 Addition of a Data Source to the Consistency Application . . . . . . . . . 27

vi DRDC Atlantic CR 2010-057

8.6.1 Data Source Client . . . . . . . . . . . . . . . . . . . . . . . . . 27

8.6.1.1 Interface with Data Source . . . . . . . . . . . . . . . 27

8.6.1.2 Interface with CA . . . . . . . . . . . . . . . . . . . . 28

8.6.2 Vocabulary Alignment . . . . . . . . . . . . . . . . . . . . . . . 29

8.6.3 CA Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

8.6.4 New Items to Compare . . . . . . . . . . . . . . . . . . . . . . . 30

8.6.5 Change the Position Source . . . . . . . . . . . . . . . . . . . . 31

8.7 Changing the Authoritative Source . . . . . . . . . . . . . . . . . . . . . 32

8.7.1 Authoritative Source . . . . . . . . . . . . . . . . . . . . . . . . 32

8.7.2 Authoritative Source Interface . . . . . . . . . . . . . . . . . . . 32

8.7.3 Vocabulary Alignment . . . . . . . . . . . . . . . . . . . . . . . 33

8.7.4 CA Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

9 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

9.1 Java Heap Space Problem While Running the CA . . . . . . . . . . . . . 35

9.2 Google Maps API Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

9.3 The CA Client is Not Responsive . . . . . . . . . . . . . . . . . . . . . . 36

References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Annex A: DRDC Atlantic Specific Installation . . . . . . . . . . . . . . . . . . . . 39

List of symbols/abbreviations/acronyms/initialisms . . . . . . . . . . . . . . . . . . 40

DRDC Atlantic CR 2010-057 vii

List of figures

Figure 1: Compare-MDA Framework Functional Diagram. Three layers areshown in the consistency application. The communication layer(yellow), the control layer (orange) and the logic layer (gray). Thecommunication layer data source clients interface with the web servicesdeveloped for each data source. . . . . . . . . . . . . . . . . . . . . . . 2

Figure 2: UML diagram showing the data source client interface. Source clientsare shown across the top of the figure. Each client must have themethods: invoke; getNewShips; getLastEntry. . . . . . . . . . . . . . . . 27

viii DRDC Atlantic CR 2010-057

1 Scope

The framework that was constructed for the Consistency Application (CA) is illustrated inFigure 1. The Compare-MDA framework includes six web services:– ASIA Web Service (WS),– SeaSpider WS,– International Telecommunication Union (ITU) WS,– CA WS,– CA client WS and– Java Universal Description, Discovery, and Integration (jUDDI) WS;– and one application: the CA.

Five databases are feeding the web services and the application. Those databases are:– the asia DB,– the seaspider DB,– the itu db DB,– the consistency DB and– the juddi DB.

Each of these components are illustrated in Figure 1.

This document gives the detailed installation guidelines for the framework. During thedevelopment, the framework became known as the Compare-MDA framework. This docu-ment provides a guideline for the data source web service development and its addition tothe CA. It also describes the procedure to change the Authoritative Source (AS).

1.1 Document OverviewThis document is divided as follow:

1. Prerequisites (Section 2)2. Database installation (Section 3)3. Tomcat installation (Section 4)4. Web services installation and execution (Section 5)5. Consistency Application installation and execution (Section 6)6. CA Client installation (Section 7)7. Compare-MDA Framework Development Environment (Section 8)

1.2 Quick Installation GuideThe main steps required for the installation of the Compare-MDA framework are:

DRDC Atlantic CR 2010-057 1

Figure 1: Compare-MDA Framework Functional Diagram. Three layers are shown in theconsistency application. The communication layer (yellow), the control layer (orange) andthe logic layer (gray). The communication layer data source clients interface with the webservices developed for each data source.

1. Install Java 1.6 and modify environment variable JAVA HOME and Path accordingly(Section 2.1).

2. Install WinAnt and add WinAnt bin directory into the environment Path (Section2.1).

3. Install MySQL server on the computers that will host the databases. Use UTF8 en-coding and enable remote access (Section 2.2).

4. Install Firefox and the Google Earth API (Section 2.4).5. Set the DSN for the asia DB (Section 2.3).6. Create the databases (Section 3.1).7. Install the itu db database (Section 3.2).8. Install Tomcat with or without jUDDI (Section 4.1 or 4.2) on each computer hosting

a web service.9. Copy the axis2.war file on each Tomcat webapps directory. Restart the Tomcat

application (Section 4.3).

2 DRDC Atlantic CR 2010-057

10. Install and deploy the four web services (aar files) using http://localhost:8080/axis2 interface (Section 5).

11. Run the Consistency Application either using the Eclipse environment (Section 6.4)or the ant command with the appropriate build.xml file (Section 6.3).

12. Deploy the comparemda.war file using the Tomcat server http://localhost:8080(see Section 7).

13. Start the application by accessing the link http://localhost:8080/compareMDA.

If the computer/databases configuration is changed, you will need to update the parameterslocated in the services.xml file of each web service (Section 8.4.5) and the propertyfile for the CA (Section 6.1). These files are easily accessible by the Eclipse environmentdescribed in Section 8.1. Then you will need to re-archive and re-deploy the services inAxis2.


2 Prerequisites

Prior to the installation of the Compare-MDA framework, it is assumed that the followingsoftware is already installed.

2.1 Java and WinAntThe following are the Java requirements.

– Java JDK 1.6 1.– WinAnt. 2

– Set environment variables: JAVA HOME and Path (JDK and WinAnt bin directories).

2.2 Databases– MySQL Server 5.0 or higher (see http://dev.mysql.com/downloads/mysql/ for

download and instructions) with the Seaspider Database (DB) installed.– MySQL Graphical user interface (GUI) tools package 3 (recommended).– Microsoft (MS) Access with the ASIA DB installed.– ASIA image directories. The structure of the ASIA image directories must match the

stored paths in the ASIA DB.

2.3 Set the Data Source NameAutomated Ship Image Acquisition (ASIA) WS is connecting to ASIA database via OpenDatabase Connectivity (ODBC). The following is required to set up a Data Source Name(DSN) on the system.

1. Open Windows’ ODBC Data Source Administrator as follows:– In Windows 95, 98, or NT, choose Start > Settings > Control Panel, then double-

click the ODBC Data Sources icon. Depending on your system, the icon couldalso be called ODBC or 32bit ODBC.

– In Windows 2000 and XP, choose Start > Settings > Control Panel > Adminis-trative Tools > Data Sources.

2. In the ODBC Data Source Administrator dialog box, click the System DSN tab.

3. Click Add to add a new DSN to the list.

1. http://java.sun.com/javase/downloads/widget/jdk6.jsp2. http://code.google.com/p/winant3. http://dev.mysql.com/downloads/gui-tools/5.0.html


4. Scroll down and select the Microsoft Access (.MDB) driver. Click Finish.

5. Type in the name ”ASIA” (no quotes, but leave the cases the same) for the DataSource Name.

6. Click SELECT and select the database (e.g.”d:\java\ASIA.mdb”).

7. Click OK all the way out.

2.4 Firefox and Google Earth APIThe application was tested on Firefox (with versions higher than 3.0) and not on InternetExplorer (IE). IE has some issues regarding standard compliance. If Firefox is not installed,download it from http://www.mozilla.com/en-US/firefox/ie.html.

Install Google Earth (GE) API (available at http://code.google.com/apis/earth/).Restart Firefox to make it effective. Note that GE API does not work on Linux. Moreover,GE API has to be used on line.

In order to run the CA client web service, a GE API key is required. To get a key, goto http://code.google.com/apis/maps/signup.html, check I have read and agreewith the terms and conditions and enter the CA client WS web site URL (e.g. http://localhost:8080/comparemda).


3 Database Installation

The Compare-MDA framework has a requirement for three databases on one or moreMySQL servers: the itu db, consistency and juddi databases. itu db content mustbe imported, while consistency is filled by the CA execution and juddi will be filledduring the installation of Tomcat-jUDDI.

3.1 Database CreationThe following command (first one) starts the MySQL application, and creates the necessarydatabases.

mysql -u root -p<enter password>CREATE DATABASE itu_db;CREATE DATABASE consistency;CREATE DATABASE juddi;GRANT ALL PRIVILEGES ON juddi.* TO ’juddi’@’localhost’IDENTIFIED BY ’juddi’ WITH GRANT OPTION;

3.2 ITU Database TransferThe following command will load the ITU database given the content in the itu_db.sqlfile.

mysql -u root -p < itu_db.sql

3.3 Enabling Remote Access to MySQL ServerIn order to have remote access to a database on a MySQL server, two modifications arerequired: (1) Replace the bind-address, (2) grant privileges to extra users. After these mod-ifications restart the MySQL server.

1. Grant all remote privileges with the mysql command:mysql -u root -pGRANT ALL PRIVILEGES ON *.* TO root@’%’ IDENTIFIED BY ’password’;

In this example, all users identified by the user name root and the password passwordhave all privileges.


2. Restart the MySQL service. It can be done using the MySQL Administrator tool orby command line:– On Windows:$ net stop mysql$ net start mysql

– On Linux:sudo /etc/init.d/mysql stopsudo /etc/init.d/mysql start

3.4 Extra SettingsIt is recommended to add the following lines in MySQL configuration file my.cnf (espe-cially for large databases such as seaspider):

max_allowed_packet=64Mwait_timeout=1000000


4 Tomcat Installation

All six web services of the Compare-MDA framework have to be deployed in a Tomcatweb server. More than one service can be deployed on a single Tomcat. There are tworestrictions regarding the configuration of the web services (and thus Tomcat servers) on anetwork for the Compare-MDA framework:

1. At least one of the Tomcat web servers should be bundled with jUDDI.

2. The ASIA WS has to be deployed on a Tomcat web server located on the samemachine that the MS Access asia DB is on. In theory, it is possible to access aremote MS Access database, but it is difficult. Therefore, a Tomcat web server mustbe installed on the machine hosting the asia DB.

Moreover, services ASIA WS, SeaSpider WS, ITU WS and CA WS need Axis2 web ser-vice to run. An Axis2 web service needs to be deployed on each Tomcat web server thatwill host one of those services.

4.1 Tomcat-jUDDIUniversal Description, Discovery, and Integration (UDDI) was implemented using jUDDI,an open source Java implementation of the UDDI specification for Web Services.

jUDDI, which is a web service itself, requires Tomcat and MySQL (or Derby) to run.The registry is persisted in a MySQL DB and is accessed with jUDDI WS (see jUDDI WSand juddi DB in Figure 1).

The following describes how to install Tomcat-jUDDI:

1. Download the last stable version of juddi-portal-bundle.zip(ex: juddi-portal-bundle-3.0.1.zip) 4.It contains Tomcat, portal, pluto, juddi-servlet and juddiv3.

2. There are three files that require modification (most of it is to switch the databasemanagement system from Derby to MySQL):

(a) Modify \webapps\juddiv3\META-INF\context.xml:Replace the content file with:

<?xml version="1.0" encoding="UTF-8"?><Context><WatchedResource>WEB-INF/web.xml</WatchedResource><Resource name="jdbc/JuddiDS" auth="Container"

type="javax.sql.DataSource"

4. http://ws.apache.org/juddi/releases.html


username="juddi" password="juddi"driverClassName="com.mysql.jdbc.Driver"url="jdbc:mysql://localhost:3306/juddi"maxActive="8"/>

</Context>

Modify it to match your setup. For example, replace ”localhost” by the InternetProtocol (IP) of the computer where your jUDDI MySQL database is located.

(b) Modify \webapps\juddiv3\WEB-INF\classes\juddiv3.properties:– Comment the 2 lines under ”Specifies UDDIs to which we subscribe”– Modify the values of juddi.server.baseurl .

It should be the URL pointing to the location of the Tomcat server (withjUDDI WS). For instance:juddi.server.baseurl=http://192.168.48.17:8080juddi.server.port.

(c) Modify webapps/juddiv3/WEB-INF/classes/META-INF/persistence.xml:Replace this line:

<property name="hibernate.dialect"value="org.hibernate.dialect.DerbyDialect"/>

with:

<property name="hibernate.dialect"value="org.hibernate.dialect.MySQLDialect"/>

(d) Start Tomcat by double-clicking on the ”startup.bat” icon in the jUDDI bindirectory. Verify that there is no error thrown in the Tomcat console.

(e) Starting Tomcat will automatically create tables in the juddi DB.

(f) It is recommended for performance issues, to replace all occurrence of the key-word ”FINE” with ”INFO” in the logging configuration file.

(g) To stop Tomcat-jUDDI, it is recommended to use the jUDDI shutdown com-mand (shutdown.bat) instead of using Ctrl-C, as it may result in the processhanging.

4.2 Tomcat Without jUDDI4.2.1 Windows

Download the Tomcat Windows installer from http://tomcat.apache.org/download-60.cgi. During installation, select the destination directory, and at the JVM panel, change thedefault to point to your JDK Java directory. The Tomcat service can be started with:


– at the comman line with $\bin\startup.bat, or– double-click on the tomcat6.exe in \bin.To stop Tomcat, do– $\bin\shutdown.bat, or– Ctrl-C in the Tomcat window.//It is also possible to control the Tomcat process by executing the Tomcat Manager tool(tomcatw.exe). This is very useful for stopping and restarting Tomcat. Also, in case ofmemory allocation problems, the user can modify the memory parameters in the Java tabof the Tomcat Manager tool. We recommend a setting of 256 MB for initial memory and1024 for Max Memory pool.

4.2.2 Linux

Download Tomcat from http://tomcat.apache.org/download-60.cgi (the Core binis enough). Set CATALINA HOME to be the base tomcat directory(e.g.CATALINA HOME=$HOME/pkg/apache-tomcat-6.0.20).Also set either the JAVA HOME to the full JDK or JRE HOME to the installed JRE. OnLinux, you will also need to add a user intomcat-users.xml (in tomcat/conf/tomcat-users.xml). To do so, just add this line:

<user username="admin" password="pw" roles="manager"/>

with the other users.

To start Tomcat, do$CATALINA HOME/bin/startup.sh

After startup, the default web applications included with Tomcat will be available at:http://localhost:8080/

To stop Tomcat, do$CATALINA HOME/bin/shutdown.sh

4.3 Axis2Download the latest stable version of Axis2 from http://ws.apache.org/axis2/download.cgi. Pick the standard bin distribution and WAR distribution. Copy axis2.war (in axis2-war) into the webapps directory of Tomcat or jUDDI. Stop and restart Tomcat.

The Axis2 home is located at http://localhost:8080/axis2/. To make sure you havethe proper environment, click on Validate and read the results. Make sure that Examining


webapp configuration and Examining Version Service passed the test.

To upload services, go to the Admin page. The default login is admin and password is axis2.It can be changed from axis2\WEB-INF\conf\axis2.xml by modifying these lines:

<parameter name="userName">admin</parameter><parameter name="password">axis2</parameter>

Services are uploaded with the Upload tool and the Browse option by uploading the .aarfiles needed.


5 Web Services Installation5.1 RestrictionThe ASIA WS has to be deployed on a Tomcat web server located on the same machinethat the MS Access asia DB is on. See Section 4.

5.2 Deployment on TomcatCopy web services AsiaDataSourceService.aar, SeaSpiderDataSourceService.aar,ItuDataSourceService.aar, CAService.aar from the Installation CD with already setDRDC IP/database parameters.

If parameters have changed, create new archives following instructions in 8.4.2.

If there is already a copy of one of those services in the \webapps\axis2\WEB-INF\services directory of Tomcat, stop Tomcat, delete it and restart Tomcat.

Go to http://IP:Port/axis2/, where IP is the full IP of the computer where Tomcatis running (can also be localhost if working locally) and Port is the Tomcat port, usually8080, but not restricted to that value.

Click on Administration, enter the login/password (by default: admin/axis2) and click onLogin. Click on Upload Service (on the left side, under Tools), choose the Browse optionand select the .aar file that you want to deploy and click on Upload. After the file has beensuccessfully uploaded, click on Available Services (on the left side, under System Com-ponents). The service should be there (may take up to one minute to upload). The WebService Definition Language (WSDL) file is accessible by clicking on the service name.

Repeat the process for all other services to be loaded.


6 CA Configuration and Execution6.1 ConfigurationEdit the consistency.properties file in ca.drdc.comparemda.consistency.

1. Set the end point location of each of the three data source web services.

2. Set the end point location of the CA WS.

3. Set the consistency DB parameters (location, user name, password).

6.2 ExecutionThe CA will fill the consistency DB with its results (identified as CA DB in Figure 1).

To run the CA:

1. Make sure that services ASIA WS, SeaSpider WS and ITU WS are deployed andrunning (run Tomcat).

2. Configure the CA parameters in ca.drdc.comparemda.consistency.CAParameter.

3. Run the main script in ca.drdc.comparemda.consistency.CAManager (see Sec-tions 6.3 and 6.4). The first time the application is launched, it takes more than onehour to fill the consistency DB, depending on the size of the databases to be pro-cessed.

4. Verify that all consistency database tables (consistencyTable, informationTable,itemTable, shipTable, sourceTable and statisticTable ) have been filled.

The CAManager (referred as the CA Manager component in Figure 1) orchestrates thechain of events leading to the comparison of ship items among sources. The Manager is ascheduled task that builds queries that are then sent to the data sources. The CAManagerreceives the responses from the data sources, and then passes these responses on for addi-tional analysis.

The key variable for the CAManager is the lastEntry field value of sourceTable(consistency DB). The value of this field indicates the time stamp of the lastreport/downloaded page for each data source. This time stamp is used by the Manager toquery the data sources for new information, from task to task. See [1] for detail about theCAManager task.

If the asia and seaspider databases are not updated frequently (on a week or monthbasis), there is no need to let the CAManager run continually. It can be stopped (see Sec-tions 6.3 and 6.4) once it has finished filling the consistency DB. There are actually printouts to follow the CAManager task evolution. These indicate how many queries to the datasources the CA still has to do. Re-launch the application just when new data is uploaded to


asia and seaspider databases.

The characteristics of the manager are controlled via input parameters defined inca.drdc.comparemda.consistency.CAParameter. Prior to starting the CA, verify thedefault parameters in the init method of the CAParameter. There are three main parame-ters to set:

1. the data sources used for comparison,

2. the items to compare with their comparison type,

3. the source providing the position, and

4. the AS and the number of hours between two queries made to the data sources.

The CA was tested with the current default values:– ASIA WS, SeaSpider WS and ITU WS as data sources.– ITU WS as AS.– ASIA WS as position source.– Ship items to compare: name (soft comparison), port (pattern comparison), type (pattern

comparison), flag (soft comparison), MMSI (hard comparison), call sign (hard compar-ison) and IMO (hard comparison).

These default values are expected to be modified when data sources are added and/or theAS changed (see Sections 8.6 and 8.7 for details about these procedures).

6.3 Running the CA at the Command LineFor executing, the Consistency Application requires connections to three web services,its own database, and many external libraries. Consequently, the CA needs to link witha long list of Java libraries. It is highly recommended to use WinAnt in concert with thebuild.xml containing all classpaths required by the CA.

To run the CA at the command line, go in the directory where the build.xml for theCA is located (actually in C:\compareMDA\workspace\consistencyApp), open a DOScommand line window and type

ant CAManager

To stop it, just use Ctrl-C.

If new classes or libraries are added to the build path of the CA, or if the code is moved toanother location, a new build.xml will have to be generated.


To create a new build.xml for the CA, use Eclipse: Right-click on consistencyAppproject > Export. Select General > Ant Buildfiles, click Next and check the consistencyApp.Click Finish.

The new build.xml will be located in workspace\consistencyApp. Open it and makesure the following lines are included:

<target name="CAManager"><java classname="ca.drdc.comparemda.consistency.CAManager"failonerror="true" fork="yes">

<classpath refid="consistencyApp.classpath"/></java></target>

If it is the case, add the lines:

<jvmarg value="-Xms256m"/><jvmarg value="-Xmx1024m""/>

between the classpath tag and </java>.

If the target name CAManager does not exist in the generated build.xml file (it may hap-pen), add the following lines at the end of the file, before the </project> tag:

<target name="CAManager"><java classname="ca.drdc.comparemda.consistency.CAManager"failonerror="true" fork="yes">

<classpath refid="consistencyApp.classpath"/><jvmarg value="-Xms256m"/><jvmarg value="-Xmx1024m""/></java></target>

6.4 Running the CA Using EclipseTo run the CA with Eclipse, right-click on the CAManager class in the Eclipse PackageExplorer. Select Run As > Java Application. If new classes or libraries are added, Eclipsewill adapt itself to these changes. There is no need to generate a build file.

To stop it, click on the red button on the Eclipse Console Panel.


7 CA Client Web Service

This section describes how to deploy the CA web client (illustrated in Figure 1 by the CAClient box). Its role is to provide the ability to browse and display the CA comparison re-sults.

The CA client WS requires Tomcat to run. Make sure that there is a Tomcat web serverinstalled and running on the machine where the CA client WS will be installed. See Sec-tion 4 for Tomcat installation procedures.

If the archive comparemda.war is not available or needs to be modified (e.g., becauseit was generated using outdated build.xml properties), build it at the command line usingant build.xml or using Eclipse. Before, make sure that the Google key is set properly(see Section 8.3.1). In eclipse right-click on the build.xml file (in the Package Explorerwindow) and then click on Project > Run As > Ant Build.

To deploy the service in Tomcat:

1. Go to http://IP:Port/, where IP is the full IP of the computer where Tomcat isrunning (can also be localhost if working locally) and Port is the Tomcat port,usually 8080, but not restricted to that value.

2. Click on Tomcat Manager, on the upper left side of the page.

3. Enter User Name and Password. On Tomcat-jUDDI, the default User Name is rootand the password is root, while on the standard Tomcat, the default User Name isadmin and the password is blank. In both cases, this information can be found andmodified in TOMCAT_HOME\conf\tomcat-users.xml.

4. If there is already an application called comparemda deployed, click on Undeployed,on the right end of the comparemda row.

5. Click on Browse in the WAR file to deploy window.

6. Select \lib\comparemda.war from caClientWS project.

7. Click on Deploy in the WAR file to deploy window.

8. Wait until OK appears in the Message box and click on comparemda link to accessthe service.


8 Development Environment

This section describes how to1. set up the development environment,2. develop web services using Axis2 Eclipse plugins,3. publish services to UDDI,4. add a data source to the CA,5. change the AS.

8.1 Eclipse InstallationIf possible, install the Web Services Tools plugin 5. Another, perhaps simpler option, is todownload EasyEclipse Server Java with the web development tools embedded in the distri-bution 6. Note that you’ll have to delete the metadata created by Eclipse installation in theworkspace, before launching EasyEclipse. Otherwise, Eclipse will corrupt the metadata.

Start Eclipse at the command line eclipse or eclipse -clean or by double-clickingon the Eclipse logo. At the first launch, click on Cancel in the JBoss Migration Windowsand close the Welcome windows.

Set the java compiler to be the installed JDK (1.6 or higher, see section 2.1 for details):Window > Preferences > Java > Installed JRE > click on Add. In the Add JRE wizard,enter a JRE name and use the Browse functionnality to select the top directory of the in-stalled JDK. Click OK, check this JRE and click OK.

It is recommended to set the compliance level of the java compiler: Window > Preferences> Java > Compiler. Set the Compiler Compliance Level to 6.0.

8.2 Eclipse Axis2 Plugins InstallationDownload the Axis2 plugins:– Axis2 Service Archive Wizard - Eclipse Plug-in– Axis2 Code Generator Wizard - Eclipse Plug-infrom http://ws.apache.org/axis2/tools/index.html. Unzip and copy the 2 result-ing directories into the Eclipse/plugins directory.

The Axis2 code generator plug-in is incomplete. Two jar files are missing from the Eclipse/plugins/Axis2CodegenWizard/lib directory:

5. http://www.eclipse.org/webtools/6. http://www.easyeclipse.org/site/distributions/server-java.html


– stax-api-1.0.1.jar 7,– backport-util-concurrent-3.1.jar 8.Copy these into the lib directory of the Axis2 code generator plug-in.

Add a mention of the backport-util-concurrent-3.1.jar into the plugin.xml filelocated in Eclipse/plugins/Axis2CodegenWizard directory. It consists of adding thefollowing lines in the runtime block:

<library name="lib/backport-util-concurrent-3.1.jar"><export name="*"/></library>

The mention to stax-api-1.0.1.jar is already present in the configuration fileplugin.xml. Start (or restart) Eclipse with the command: eclipse −clean.

8.3 Creating Eclipse Projects from Java CodeFor the Compare-MDA framework, five projects have to be created from the java code onthe installation CD://– asiaWS from the code asia ws,– seaspiderWS from the code seaspider ws,– ituWS from the code itu ws,– consistencyApp from the code consistency app,– caClientWS from the code ca client ws.

Prior to creating the projects, copy the code from the installation CD, to the system whereEclipse is installed. It is recommended also to copy the pkgs/lib directory and to install itoutside the installation directory but close to your workspace because, Eclipse will createa link between them.

To create an Eclipse project from existing java code on the system, follow these instruc-tions:

1. Create a Java Project:Click on File > New > Project. Select Java > Java Project > Next. In the New JavaProject wizard, enter the Project name (e.g., ituWS), select Create separate sourceand output folder and click Next. Verify that the output folder is ituWS/bin and clickFinish. If Eclipse pops up a window asking about selecting Java Specifications, youmay click Yes.

7. http://dist.codehaus.org/stax/jars/8. http://sourceforge.net/projects/backport-jsr166/files/backport-jsr166/


In the case of the caClientWS project, see section 8.3.1.

2. Import files:Right-click on the project (in the Package Explorer window) > Import > General >File System > Next. In the Import wizard, select the directory to import from withthe Browse button. Choose the top directory (e.g., itu ws) and then select src andWebContent directories from the wizard. Click Finish.

3. Create the Eclipse Axis2 library:Select Windows>Preferences>Java>Build Path>User Libraries. Click on New andname the library Axis2. Click on Add Jars and select all jar files located in the libdirectory of Axis2 HOME. Click OK. This is done only once and the user libraryAxis2 can be reused for other projects that require the same set of libraries.

4. Add libraries to the build path:Projects have the following dependencies to libraries:– asiaWS: Axis2 library, mysql−connector−java−3.0.17−ga−bin.jar 9

– seaspiderWS: Axis2 library,mysql−connector−java−3.0.17−ga−bin.jar

– ituWS: Axis2 library, mysql−connector−java−3.0.17−ga−bin.jar

– consistencyApp:– Axis2 library,– mysql−connector−java−3.0.17−ga−bin.jar,– simmetrics jar v1 6 2 d07 02 07.jar 10,– gson-1.4.jar 11,– commons-configuration-1.6.jar 12,– commons-collections-3.2.1.jar 13,– uddi-ws-3.0.0.jar, juddi-client-3.0.0.jar,juddi-core-3.0.0.jar 14

(for jUDDI publishing only),– soap-2.3.1.jar 15(for jUDDI publishing only).

– caClientWS: no dependency.

To add the Axis2 library to the build path:Right-click on Project > Build Path > Add Libraries > User Library>Next. Select

9. http://www.mysql.com/downloads/connector/j/10. http://sourceforge.net/projects/simmetrics/11. http://code.google.com/p/google-gson/downloads/list12. http://commons.apache.org/downloads/download_configuration.cgi13. http://commons.apache.org/downloads/download_collections.cgi14. Tomcat-juddi\webapps\juddiv3\WEB-INF\lib15. http://www.jarfinder.com/index.php/jars/versionInfo/927


Axis2 and click Finish.

To add external archives to a project, Right-click on Project > Build Path > AddExternal Archives. Select all the required jar and click Open.

5. Add projects to build path:For the consistencyApp project, add asiaWS, seaspiderWS and ituWS projects:Build Path > Configure Build Path. In the Projects window, click on Add and selectthe three projects.

Note that Eclipse compiles in real time. Errors are indicated with a red box.

8.3.1 caClientWS Project

The caClientWS project differs from the other ones because it does not only host pure javacode ( javascript/jsp and html code needed to display the client in an internet browser). Thefollowing describes the special requirements related to this project:

1. At the project creation step, choose Use project folder as a root for sources and classfile instead of Create separate source and output folder and click Finish.

2. If consistencyApp project has been modified, export it asconsistencyapplication.jar to caClientWS\public_html\WEB-INF\lib.There is no need to include WebContent in the archive. The Export command islocated in the Eclipse File menu. In the Export window, deploy the Java tab andselect the Jar File type. It is important to precisely enter the destination directory forthe export as stated above.

3. If asiaWS project has been modified, export it as asia.jar to caClientWS\public_html\WEB-INF\lib. There is no need to include WebContent in the archive.

4. If required, generate a new GE API (see section 2.4). Paste the key at the top ofcaClientWS\public_html\clientinterface.html:<script type="text/javascript"src="http://www.google.com/jsapi?key=ABQIAAAA7E2KYt7ucEuar6ce3kjkMRQHlAky8CDYm1IokzD4a8EMjDN-mUU4nw"></script>

NOTE: Do not page a line break in the key.


8.4 Data Service Development Using Eclipse Axis2Plugins

This section describes how to develop a SOAP web service using Axis2 Eclipse plugins. Itcovers the generation of the archive, the WSDL file and the client stubs code. The approachused is the Bottom-Up approach, which involves creating a Web service from a Plain OldJava Object (POJO).

It assumes that Eclipse with the Web Tools Platform (WTP) and Axis2 plugins are in-stalled.

The following instructions are an adaptation of the tutorial Bottom Up Apache Axis2Webservice with Eclipse 16. These instructions can be applied to other contexts than theCompare-MDA one, but in order to provide a concrete example, we’ll use the ITU WScase.

8.4.1 Bottom-Up Development

Bottom-Up web service development involves creating a web service from a POJO. Thissection describes the required java classes to develop a web service using the bottom-upapproach.

In these classes, there should be a class (ItuDataSource for ITU) with all the methodsto be exposed as operations for the web service. The group may also contain classes en-capsulating the data required for those functions to run and other classes required to workproperly. In the ITU case, the group is composed of the following classes: ItuDataSource,ItuDBManager and classes included in the following directories: model\, query\ andweb\.

It is important to be aware that all methods with a name starting with set or get, in theobjects instantiated in ItuDataSource, will be exposed as data in the interface (WSDLfile).

Create a main method for ItuDataSource to debug all methods to be exposed. Removethat main before archiving.

Write log4j configuration file named log4j.properties in WS_PROJECT\src directoryof the project. This will avoid warning messages when running the application. Copy thoselines in the file:

16. http://yuniarko.com/bottom-up-apache-axis2-webservice-with-eclipse.html


# Set root category priority to INFO and set its only appender to A1log4j.rootCategory=INFO, A1

# A1 is set to be a ConsoleAppender (writes to system console).log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.log4j.appender.A1.layout=org.apache.log4j.PatternLayoutlog4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

8.4.2 Archiving

Once the (ItuDataSource) methods are debugged, the next step is to generate an archive.

In Eclipse, select the Java Perspective.

In the Package Explorer panel, select the project hosting the web service code, Right Click> New > Other > Axis2 Wizards > Axis2 Service Archiver.

1. Select Class File Location where the output class is located (e.g., WS_PROJECT\bin).Choose Include .class only. Click Next.

2. Select Skip WSDL. Click Next.

3. Add any jar library you use. Click Next. For the Compare-MDA data services, addmysql-connector-java-3.0.17-ga-bin.jar (or a more recent version). For theCA WS, add alsocommons-configuration-1.6.jar and commons-collections-3.2.1.jar.

4. Deselect Generate the xml file automatically and give the location of theservices.xml (in WS_PROJECT\WebContent\WEB-INF for Compare-MDA). If theservice does not require a database connection, the Generate the xml file automati-cally can be chosen. Click Next.

5. Insert Output file location and Output File Name. The output location is not im-portant, since the file will be uploaded in Tomcat/webapp. Choose a name that ismeaningful (e.g., ItuDataSourceService). Click Finish.

8.4.3 WSDL

In the Package Explorer panel, select the project hosting the web service code. Right Click> New > Other > Axis2 Wizards > Axis2 Code Generator.

1. Choose Generate a WSDL from a Java source file. Click Next.


2. Enter required class in the Fully Qualified Class name text box (e.g., ca.drdc.comparemda.data.itu.ItuDataSource).

3. Click on Add Folder and select the output class location (\url{WS_PROJECT\bin}).

4. Click on Add Jar and select axis2-1.5-kernel.jar(from \url{AXIS2_HOME\lib}).

5. Click on Test Class Loading and make sure to have the message Class file loadedsuccessfully.

6. Let default values assigned, but make sure the Service Name is the right one. ClickNext.

7. Insert Output file location and Output File Name. Suggestion: Create a wsdl direc-tory in the WebContent directory of the current project. Choose this wsdl directoryfor Output file location. Change the suggested Output File Name to a more meaning-ful name. It could be the same name as the .aar file.

8. Click Finish. Remark: if the modifications described in 8.2 are not completed at thispoint, there will be a java.lang.reflect.InvocationtargetException.

8.4.4 Client Stub

In the Package Explorer panel, select the project hosting the web service code, Right Click> New > Other > Axis2 Wizards > Axis2 Code Generator.

1. Choose Generate Java source code from a WSDL file. Click Next.

2. Select the WSDL file generated before. Click Next.

3. Assign the default values. Click Next.

4. Choose Output path to be the same directory of the project (not deeper) to make iteasy. Check Add Axis2 libraries to the codegen result project. Select AXIS2 HOMEwhere the Axis2 Standard Binary Distribution is located. Click Check Libs and makesure a message shows the Axis libs as being loaded successfully. Click Finish.

5. Refresh the project. Two classes have been added: CallbackHandler.java and aStub.java. Also there is a new directory lib that contains required jar to runAxis2. Add those jars to the build path project if required.

6. For Compare-MDA, these classes are located in ca.drdc.comparemda.data.client.

Now everything is there to allow the client code use of the service. Refer to http://yuniarko.com/bottom-up-apache-axis2-webservice-with-eclipse.html for ex-amples of Synchronous and Asynchronous clients or to the Compare-MDA client codeca.drdc.comparemda.consistency.client for synchonous examples.


8.4.5 Data Service

A correct approach to expose a database as a web service is to get the life cycle manage-ment support from Axis2.

The first step is to write the life cycle management class. This class is where you create andstore the database connection. It should be noted here that when Axis2 starts up (at the timeof service deployment), the ServiceLifeCycle class will be invoked; also, when the sys-tem goes down, the ServiceLifeCycle class will be invoked again. The DB connectionis created at the service deployment time and stored inside the ConfigurationContext object.

The life cycle management class implements the interface ServiceLifeCycle.

For service using the ServiceLifeCycle, the cycle management class must be mentionedin the services.xml file. Moreover, the database information is also listed in this file.Below is the services.xml for ItuDataSourceService data service. The mention about thecycle management class (ItuDBServiceLifeCycle) is at the second line:

<service name="ItuDataSourceService"class="ca.drdc.comparemda.data.itu.ItuDBServiceLifeCycle" >

<Description>DataService exposing the ITU web site data base.</Description>

<messageReceivers><messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"

class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/><messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"

class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/></messageReceivers><parameter name="ServiceClass"

locked="false">ca.drdc.comparemda.data.itu.ItuDataSource</parameter><parameter name="jdbcDriver">

com.mysql.jdbc.Driver</parameter><parameter name="jdbcConnectionURL">

jdbc:mysql://192.168.48.12:3306/itu_db</parameter><parameter name="jdbcConnectionUser">root</parameter><parameter name="jdbcConnectionPassword">root</parameter>

</service>

See services.xml of ASIA WS for an example with MS Access.


When creating the archive (see Section 8.4.2), it is important to add the mysql.connectorjar file at step 3 of the archive creation. At step 4 of the archive creation (Select the ServiceXML file to be included in the Service archive) the Generate the xml file automaticallycheck box must not be selected and the location of services.xml file created before mustbe given.


8.5 Publishing ServicesUDDI was implemented using jUDDI, an open source Java implementation of the UDDIspecification for Web Services.

jUDDI, which is a web service itself, requires Tomcat and MySQL (or Derby) to run. Theregistry is persisted in a DB in the MySQL database management system and is accessedwith jUDDI WS (see jUDDI WS and juddi DB in Figure 1).

The class used to publish services is inca.drdc.comparemda.publish.DataSourcePublisher. Note that this class can be re-moved from the CA project. There are no dependencies between the DataSourcePublisherand the CA.

To publish web services, run the main method of DataSourcePublisher. Prior to run-ning the script, make sure that all parameters are set properly.

Service parameters are set directly in methods. Comments in the code indicate where pa-rameters should be modified. The main parameters to edit are the business information,service name, end points and user information. See [2] for information about UDDI.

Once a service is published, the information appears in the juddi DB.

Note that the DataSourcePublisher class offers the capability to publish only, not todelete nor bind with any of the published services.


8.6 Addition of a Data Source to the ConsistencyApplication

8.6.1 Data Source Client

The first step to link a Data Source (DS) to the CA is to build a DS client. The DS clientsare located in the package ca.drdc.comparemda.consistency.client. A new direc-tory must be added for each new data source client, in order to preserve the actual struc-ture. Moreover, for uniformity, the DS Client name should follow the form DsnameClient,where dsname is the name of the directory containing the client.

The client interfaces with the data source and the CA, as described in Figure 2.

Figure 2: UML diagram showing the data source client interface. Source clients are shownacross the top of the figure. Each client must have the methods: invoke; getNewShips;getLastEntry.

8.6.1.1 Interface with Data Source

In the case of a web service client, the client code development depends on the SOAP en-gine used. If the data source is simply a database on the network, the client must instantiatethe connection and include the required DB interface methods.

If the DS is a web service with a WSDL interface, it is possible to automatically gener-ate client stub code (see section 8.4.4 for instructions with Axis2). What is refered to theDS client here is a java class communicating with the DS using the stub. The client stuboffers the necessary methods to call and process web service operations. For instance, the


stub is responsible for translating the SOAP message in/out into java objects. It exposesoperations input and responses as java objects, with their respective getters and setters.

See classes– ca.drdc.comparemda.consistency.client.asia.AsiaClient,– ca.drdc.comparemda.consistency.client.seaspider.SeaSpiderClient,– ca.drdc.comparemda.consistency.client.itu.ItuClient.for example of DS clients interfacing with client stub.

8.6.1.2 Interface with CA

In order to interface with the CA, each data source client must implement theca.drdc.comparemda.consistency.client.DataSourceClient interface. The inter-face contains three methods: invoke, getNewShips and getLastEntry. See javadoc for thedetailed description of these methods and see examples of implementation with– ca.drdc.comparemda.consistency.client.asia.AsiaClient,– ca.drdc.comparemda.consistency.client.seaspider.SeaSpiderClient,– ca.drdc.comparemda.consistency.client.itu.ItuClient (for a static data source client ex-

ample).

The method invoke is used to invoke the Data Source web service, based on a query. Ittakes a ca.drdc.comparemda.consistency.model.Query object as input and returnsa list of ca.drdc.comparemda.consistency.model.Ship (referred as CAShip in thisdocument) satisfying the input query.

The method getNewShips gets the names of the ships corresponding to a date equal orhigher than the input date. It takes a date in seconds as input and returns a list of Stringscorresponding to the names of the ships satisfying the query. For clients of static datasources (e.g., ITU), which are not updated periodically with new entries, the implementa-tion of this method must always return an empty list.

The method getLastEntry gets the latest entry date of the data source service DB. It re-turns the latest update date in seconds. For clients of static data sources (e.g., ITU), whichare not updated periodically with new entries, the implementation of this method must al-ways return 0.

Since the CA and the additional DS probably don’t share the same vocabulary, alignmentis required to transform:

1. CA query into a query understandable for the new DS,

2. DS response as CAShips.


8.6.2 Vocabulary Alignment

The vocabulary alignment is performed inca.drdc.comparemda.consistency.vocabulary.ObjectAlignment. This class holdsstatic alignment methods for each data source. At least 2 methods are required for theaddition of a data source:

1. sourceToCAShips, which transforms the data source response sequence of complextypes into a list of CAShips.

2. caToSourceQuery, which transforms the CA query into a query understandable bythe data source.

See asiaToCAShips, seaspiderToCAShips, ituToCAShips, caToAsiaQuery,caToSeaspiderQuery and caToItuQuery for examples of implementation.

Note that in the case of a data source wrapped as a SOAP web service, the data sourceclient will use the service’s client stub. The stub exposes the input and responses as javaobjects, with their respective getters and setters. That way, the alignment is straightforwardbecause it consists of mapping the response objects to CA data model objects (CAShips).

Additional alignment methods may be required to transform some ship items into com-parable self-describing parameters. For instance, the ASIA Data Source Service returnsship type as AIS ship type numeric code. The numeric code is mapped to its descriptionthrough the vocabulary solution (see ObjectAlignment.asiaToCAType). Flags, types anddate are the parameters that will the most likely require alignment.

8.6.3 CA Parameters

The class ca.drdc.comparemda.consistency.CAParameter holds the parameters of theCA. CAParameter object is instantiated at the application startup. Some of its parametersare also persisted in the consistency database. At the addition of a data source, the CA-Parameter class has to be modified. There are 3 steps required to modify CAParameter forthe addition of a DS:

1. Add a private variable containing the name of the DS: Add a private variable con-taining the name of the new data source (see ASIA, SeaSpider and ITU variables):private static String DSNAME_SOURCE = "dsname";You will also have to implement the getter/setter methods to access the variable.

2. Modify the method init to add the DS to the list of data sources: In init(), add thenew data source to the list of data source names (such as for ASIA, SeaSpider andITU):dataSourceNames.add( DSNAME_SOURCE );

3. Modify the getClientToName method to add an instance of the DS client: Add acase, in the for loop of getClientToName, for the new DS. The DataSourceClient


object must be instanciated with the implementation of the new DS:

for( String clientName : getDataSourceNames() ){if( clientName.equals( ASIA_SOURCE ) ){AsiaClient asiaClient = new AsiaClient();clientToName.put( asiaClient, ASIA_SOURCE );

}else if( clientName.equals( SEASPIDER_SOURCE ) ){SeaSpiderClient seaspiderClient = new SeaSpiderClient();clientToName.put( seaspiderClient, SEASPIDER_SOURCE );

}else if( clientName.equals( ITU_SOURCE ) ){ItuClient ituClient = new ItuClient();clientToName.put( ituClient, ITU_SOURCE );

}}

8.6.4 New Items to Compare

The addition of a new data source brings the opportunity to compare additional items (e.g.,ship size which is available only for ASIA). It may also be required that new items be addedfrom the CA. The addition of items to compare is done in 2 steps:

1. Modification of the Ship class:This step is required only if the new item is not already a parameter for the CAShip.If it is not the case, add the parameter along with its getter/setter methods inca.drdc.comparemda.consistency.model.Ship class. Make it a public field (atrun time, the consistency check algorithms use reflection on the Ship class to get theparameter values).

Add also a method to get the parameter name. For instance, if a new parameter calledattribute is added, implement the method getAttributeExpression:public static String getAttributeExpression() {

return "attribute";}This method will give access to the exact parameter name, without having to rewritesomewhere else in the code.

2. Addition of the items and their comparison mode into the CAParameter class:The list of items to compare is a hashmap where the key is the item’s name and thecorresponding value is the comparison mode. The comparison mode is either hard,


soft or pattern. Usually, a hard comparison is preferred for items with a numericvalue or items where typographic errors are unlikely to happen (such as flag). Pat-tern comparison is for items with a value described by a complex expression, such asa sentence. Typical example of an item requiring pattern comparison is the ship type.Soft comparison is for items with a value described by 2 words or less and wheretypographic errors are frequent. See Final Report for details about the comparisontypes.

The following code is taken from the init() method and illustrates how items areadded for comparison:

HashMap<String,String> items = new HashMap<String,String>();items.put( Ship.getNameExpression(),SOFT_COMPARISON );...items.put( Ship.getCallSignExpression(),HARD_COMPARISON );setItemsWithComparisonType( items );

8.6.5 Change the Position Source

The position of a ship is stored in the consistency table InformationTable. The posi-tion stored (latitude, longitude) is the position as reported by the positionSource, set inthe CAParameter class. Currently, the position source is ASIA. To change the positionsource, the only action required is to change the input name of the setPositionSource(DSNAME SOURCE ) method in init().

Make sure that the source chosen as the position source provides ship’s position. More-over, the method sourceToCAShips (see the first method listed in 8.6.2) must includecode to set the position of the CA ship from the Data Source information. For example, seeasiaToCAShips method:

Position caPosition = new Position();caPosition.setLatitude(asiaLastReport.getDynamicShipInformation().

getPredPosition().getLatitude());caPosition.setLongitude(asiaLastReport.getDynamicShipInformation().

getPredPosition().getLongitude());caShip.setPosition( caPosition );


8.7 Changing the Authoritative SourceThis section describes the procedure to change the Authoritative Source. The AS is cur-rently set to be the ITU WS.

8.7.1 Authoritative Source

The first step to change the AS is to build an AS client. The AS client will be located in thepackage ca.drdc.comparemda.consistency.client. A new directory must be addedfor each new AS client, in order to preserve the actual structure. Moreover, for uniformity,the AS Client name should be AsnameClient, where asname is the name of the directorycontaining the client.

8.7.2 Authoritative Source Interface

In order to interface with the CA, an AS client must implement theca.drdc.comparemda.consistency.as.AuthoritativeSource interface. The interfacecontains 2 methods:– getUidNames()– getShipWithUid( String uidName, String uidValue )

See the javadoc for the detailed description ofca.drdc.comparemda.consistency.as.AuthoritativeSource methods and see an ex-ample of implementation inca.drdc.comparemda.consistency.client.itu.ItuClient.

The method getUidNames returns a list of Strings representing the name of the AS uniqueidentifiers (uids). Uids are a combination of ship items that uniquely define a ship. There-fore, the getUidNames method must return the combination of data items that uniquelydefine a ship in the AS DB. The returned uids must be aligned with the CA vocabulary.The uids are used by the ca.drdc.comparemda.consistency.ShipMatcher algorithmsto identify ship objects corresponding to the same entity. Note that it is possible that onlyone data item uniquely defines a ship for the AS.

The method getShipWithUid takes as input the name of the uid and its value, and returns aca.drdc.comparemda.consistency.model.Ship (CAShip) satisfying the input query,i.e., with the data item named “uidName” having the value “uidValue”. It returns the nullobject if no such ship exists. Since the CA and the AS probably don’t share the same vo-cabulary, alignment may be required to transform the terms. The alignment is composed of2 steps:

1. CA uid name into a parameter understandable for the AS,


2. AS response as CAShips.

Note that a DS can also play the role of an AS, but is not required to. Seeca.drdc.comparemda.consistency.client.itu.ItuClient for an example of a webservice client implementing both the DataSourceClient and AuthoritativeSource in-terfaces. Note also that the current architecture does not require an AS be exposed as a webservice. The AS could be a simple local data base, and therefore the AS client would besimply a java class interfacing with the AS DB.

8.7.3 Vocabulary Alignment

See Section 8.6 for details about the vocabulary alignment through theca.drdc.comparemda.consistency.vocabulary.ObjectAlignment class.

8.7.4 CA Parameters

The class ca.drdc.comparemda.consistency.CAParameter holds the parameters of theCA. CAParameter object is instantiated at the application startup. Some of its parametersare also persisted in the consistency database. The 3 steps to modify CAParameter ac-cordingly to a change of AS are:

1. Add a private variable containing the name of the AS:private static String ASNAME = "asname";You will also have to implement the getter/setter methods to access the variable.

2. Modify the method init to set the AS name:Set the name of the AS to ASNAME (the variable AS holds the name of the authori-tative source):AS = ASNAME;

3. Modify the getAuthoritativeSource method to add an instance of the AS client:The current state of the code is listed below:

public AuthoritativeSource getAuthoritativeSource(){if( this.authoritativeSource == null ){if( StringComparison.isEqual( AS, ITU_SOURCE ) ){if( getClient( ITU_SOURCE ) == null ){setAuthoritativeSource( new ItuClient() );}else


{setAuthoritativeSource((AuthoritativeSource)getClient(ITU_SOURCE));}}}return this.authoritativeSource;}The implementation of getAuthoritativeSource for a new AS consists of addinga new case:if( StringComparison.isEqual( AS, ASNAME ) ){if( getClient( ASNAME ) == null ){setAuthoritativeSource( new AsnameClient() );}else{setAuthoritativeSource((AuthoritativeSource)getClient(ASNAME));}}


9 Troubleshooting

This section describes possible problems that may occur with the Compare-MDA frame-work.

9.1 Java Heap Space Problem While Running the CACause

This error can be thrown by Eclipse (if the CAManager is executed by Eclipse) or byTomcat.

Solution

Adjust the memory settings of Eclipse and Tomcat.

For Eclipse:Edit eclipse-home/eclipse.ini to have:

-vmargs-Xms512m-Xmx1024m

and restart Eclipse with eclipse -clean. If the Xmx parameter is too high (higher than thephysical memory), the error Could not create the Java virtual machine will be thrown.

For Tomcat: Add the lineset JAVA OPTS=-Xms750m -Xmx1400min tomcat-install\bin\catalina.bat.

Note that there is possibly a memory leak issue with jUDDI. Therefore, we recommendto make a minimal use of Tomcat-jUDDI, i.e deploy a minimum number of services onTomcat-jUDDI.

9.2 Google Maps API KeyWhen trying to launch the CA client WS, the following message appears in the GE window:This web site needs a different Google Maps API key. A new key can be generated at http://code.google.com/apis/maps/.


Cause

The key used within clientinterface.html is not suited for the machine on which theweb client is running on. For instance, it may appear if the key was generated for http://localhost:8080/comparemda instead of using to full machine’s IP.

Solution

Regenerate a key and create and deploy a new archive for the CA client (see Section 7 forinstructions).

9.3 The CA Client is Not ResponsiveCause

Either the query was not correctly sent to the server or the web client can’t connect properlyto the CA web service. There may be many reasons for the latter cause.

Solution

1. Verify the log files of the Tomcat server where the web client is deployed. Log filesare located in TOMCAT_HOME\logs. Look first in the catalina file. This will provideinformation about the cause of the problem.

2. The machines where either the web services or one of the databases are located, maybe off the network. Reset the connections, stop, then restart the Tomcat server.

3. One of the web servers, where other web services (i.e., not web client) are deployed,may have stopped or encounter an error. Stop and then restart that web server andrestart the web client Tomcat server.


References

[1] St-Hilaire, M.-O. (2010), Determining the consistency of information betweenmultiple systems used in maritime domain awareness, (DRDC Atlantic CR 2010-056)Defence R&D Canada – Atlantic.

[2] Chase, Nicholas (2006), Understanding Web Services specifications, Part 3: UniformDescription and Discovery Interface (UDDI). IBM developerWorks.




Annex A: DRDC Atlantic Specific Installation

The following instructions are specific to the installation at DRDC Atlantic.

Machine Name: Compare MDA Client

1. Check that services are running:(a) Startup machine (no username or password)(b) When the machine has started right click on My Computer and choose Manage

| Services and Applications | Services(c) Ensure Apache Tomcat 6 has been started(d) If it is not set to automatically start you can set it by right click | Startup Type

| choose Automatic(e) Ensure MySQL service has been started

2. Test Tomcat is running:

(a) Start Firefox web browser(b) Go to http:\\localhost:8080

(c) The local Tomcat home page is displayed

3. Run Compare MDA web page:(a) Start Firefox web browser(b) Go to http:\\localhost:8080\comparemda

(c) Type something in the Ship Name field (e.g., - OOCL)(d) Click Submit button(e) Click the Browse Results link(f) A list of ships matching your ship name is displayed(g) Click on a ship until one is shown with a picture(h) If none have a picture the Compare MDA ASIA DB machine may not be run-

ning or available

Machine Name: Compare MDA ASIA DB

1. Check that services are running:2. Startup machine (no username or password)3. When the machine has started right click on My Computer and choose Manage |

Services and Applications | Services4. Ensure Apache Tomcat 6 has been started5. If it is not set to automatically start you can set it by right click | Startup Type |

choose Automatic


List ofsymbols/abbreviations/acronyms/initialisms

API Application programming interfaceAS Authoritative SourceASIA Automated Ship Image AcquisitionCA Consistency ApplicationCG Comparison GroupDB DatabaseDS Data SourceDSN Data Source NameGE Google EarthGUI Graphical user interfaceIE Internet ExplorerIP Internet ProtocolITU International Telecommunication UnionjUDDI Java Universal Description, Discovery, and IntegrationMDA Maritime Domain AwarenessMS MicrosoftMTOM Message Transmission Optimization MechanismODBC Open Database ConnectivityPOJO Plain Old Java ObjectUDDI Universal Description, Discovery, and IntegrationWS Web ServiceWSDL Web Service Definition LanguageWTP Web Tools Platform


Distribution list


Internal distribution1 F. Desharnais

1 T. Hammond

2 A. W. Isenor (1 hardcopy; 1 CD)

1 L. Lapinski

1 A. MacInnis

1 M. McIntyre

1 S. Webb

3 Library (1 hardcopy; 2 CDs)

Total internal copies: 11

External distribution1 Library and Archives Canada,

Atten: Military Archivist Governments Records Branch

1 NDHQ/DRDKIM 2-2-5

1 Steve HorneDRDC CORA MARPAC JTFP Victoria, BC, V9A 7N2

2 Marie-Odette St-Hilaire (1 hardcopy; 1 CD)OODA Technologies Inc.4891 Av. Grosvenor,Montreal Qc, H3W 2M2

1 Laura Ozimek DSTM 5DRDC Corporate 305 Rideau Street Ottawa

1 Jean RoyDRDC Valcartier 2459 Boul. Pie XI Nord Quebec, G3J 1X5

1 Andrew WindMARLANT HQ 3rd Floor Room 311 Halifax, NS, B3K 5X5

1 Benny WongDRDC Corporate 305 Rideau Street Ottawa


Total external copies: 9

Total copies: 20


DOCUMENT CONTROL DATA(Security classification of title, body of abstract and indexing annotation must be entered when document is classified)

1. ORIGINATOR (The name and address of the organization preparing thedocument. Organizations for whom the document was prepared, e.g. Centresponsoring a contractor’s report, or tasking agency, are entered in section 8.)

OODA Technologies Inc.4891 Av. Grosvenor, Montreal Qc, H3W 2M2

2. SECURITY CLASSIFICATION (Overallsecurity classification of the documentincluding special warning terms if applicable.)

UNCLASSIFIED

3. TITLE (The complete document title as indicated on the title page. Its classification should be indicated by the appropriateabbreviation (S, C or U) in parentheses after the title.)

Installation and developer guide for the MIKM consistency application

4. AUTHORS (Last name, followed by initials – ranks, titles, etc. not to be used.)

St-Hilaire, M.-O.; Mayrand, M.

5. DATE OF PUBLICATION (Month and year of publication ofdocument.)

July 2010

6a. NO. OF PAGES (Totalcontaining information.Include Annexes,Appendices, etc.)

54

6b. NO. OF REFS (Totalcited in document.)

2

7. DESCRIPTIVE NOTES (The category of the document, e.g. technical report, technical note or memorandum. If appropriate, enterthe type of report, e.g. interim, progress, summary, annual or final. Give the inclusive dates when a specific reporting period iscovered.)

Contract Report

8. SPONSORING ACTIVITY (The name of the department project office or laboratory sponsoring the research and development –include address.)

Defence R&D Canada – AtlanticP.O. Box 1012, Dartmouth, Nova Scotia, Canada B2Y 3Z7

9a. PROJECT NO. (The applicable research and developmentproject number under which the document was written.Please specify whether project or grant.)

11HL

9b. GRANT OR CONTRACT NO. (If appropriate, the applicablenumber under which the document was written.)

W7707-098-207

10a. ORIGINATOR’S DOCUMENT NUMBER (The officialdocument number by which the document is identified by theoriginating activity. This number must be unique to thisdocument.)


10b. OTHER DOCUMENT NO(s). (Any other numbers which maybe assigned this document either by the originator or by thesponsor.)

11. DOCUMENT AVAILABILITY (Any limitations on further dissemination of the document, other than those imposed by securityclassification.)( X ) Unlimited distribution( ) Defence departments and defence contractors; further distribution only as approved( ) Defence departments and Canadian defence contractors; further distribution only as approved( ) Government departments and agencies; further distribution only as approved( ) Defence departments; further distribution only as approved( ) Other (please specify):

12. DOCUMENT ANNOUNCEMENT (Any limitation to the bibliographic announcement of this document. This will normally correspondto the Document Availability (11). However, where further distribution (beyond the audience specified in (11)) is possible, a widerannouncement audience may be selected.)

13. ABSTRACT (A brief and factual summary of the document. It may also appear elsewhere in the body of the document itself. It is highlydesirable that the abstract of classified documents be unclassified. Each paragraph of the abstract shall begin with an indication of thesecurity classification of the information in the paragraph (unless the document itself is unclassified) represented as (S), (C), (R), or (U).It is not necessary to include here abstracts in both official languages unless the text is bilingual.)

A service oriented architecture is used to construct a set of web services that interface to ap-plications previously created by the Maritime Information and Knowledge Management group atDRDC Atlantic. The services link the Automated Ship Image Acquisition System (ASIA) and theSeaSpider application. This report describes the installation procedure for the developed soft-ware. The report covers software prerequisites such as the database management system, java,and Google Earth plugins. The installation of the databases, Tomcat, the web service clients,and the consistency application are also described. The procedures for developing a new dataservice, adding a new data source, or changing the authoritative source are also documented.

14. KEYWORDS, DESCRIPTORS or IDENTIFIERS (Technically meaningful terms or short phrases that characterize a document and couldbe helpful in cataloguing the document. They should be selected so that no security classification is required. Identifiers, such asequipment model designation, trade name, military project code name, geographic location may also be included. If possible keywordsshould be selected from a published thesaurus. e.g. Thesaurus of Engineering and Scientific Terms (TEST) and that thesaurus identified.If it is not possible to select indexing terms which are Unclassified, the classification of each should be indicated as with the title.)

trustconsistent informationmultiple information sources

Date post:	01-Sep-2018
Category:	Documents
Upload:	trinhtuyen
View:	251 times
Download:	0 times

Installation and developer guide for the MIKM...

Documents