Menu
▾
▴
Tree [f9d852] v1.5 / History
Read Me
MARKOS CODE ANALYSER DATA RETRIEVAL SERVICE
INSTALLATION GUIDE
S/W tools prerequisites:
To run markos-code-analyser-data-retrieval component as w restful web service the following tools are required:
- web application container (e.g., Apache Tomcat, GlassFish) installed on the operating system,
- Java 1.7,
- Maven 3 (for building the web service and packaging into war archive),
- access to MySQL database with loaded Code Analyser Database dump.
MARKOS CA DB Data dump published on 15.04.2014
I. Build and Installation using Maven3:
0. Make sure the test data is available at MySQL database server.
1. Check out the source code from Markos GIT repository master branch:
git clone
ssh://username@git.code.sf.net/p/markosproject/code-analyser-data-retrieval master
2. Config settings:
In the src\main\resources\config\retrievalConfig.xml set the following values:
- dbUrl (an URL to the MySQL instance with testdata), e.g. jdbc:mysql://localhost:3306/markos_code_analyser_db_sp5
- user (user name for db connection)
- passwd (password for db connection)
3. Building web service WAR archive:
Run command: mvn clean package in the project home directory (where .pom file is located)
This builds a WAR archive of the service and places it in the /target directory.
4. Deploying onto web application container:
4.1 Deploying onto web application container of your choice:
Copy the WAR archive into webapps folder of you web application container (e.g. Apache Tomcat).
Make sure your web app container uses java sdk 1.7.
Run the web application container.
By default the service is available at URL: http://localhost:8080/markos-code-analyser-data-retrieval/
4.2 Alternatively you can build and run the service onto the embedded GlasFish server by executing the command: "mvn clean install -Pgf".
Make sure you use java sdk 1.7. It builds the WAR archive and deploys it at embedded GlassFish server. Then the service is made available at default URL:
http://localhost:8080/markos-code-analyser-data-retrieval/
5. Example of web service client calls from java code:
In test package there is an Example class which shows how to use Jersey REST client API to call the methods of the service.
Please mind that by default the RESTful API is available at context, what is also described in code comments:
http://localhost:8080/markos-code-analyser-data-retrieval/rest/dataretrieval/
Current Y2 development version of markos-code-analyser-data-retrieval is available at:
https://markos.man.poznan.pl/markos-code-analyser-data-retrieval-dev/rest/dataretrieval/
DEVELOPERS GUIDE
I. General
The markos-code-analyser-data-retrieval project is a RESTful web service which uses Jersey JAX-RS framework.
It retrieves project analysis data from Code Analyser MySQL database, builds XML representation (aligned with markos_code_analyser_db_schema.xsd schema) and
sends the XML over HTTP.
To call the service methods from the Java code level a use of Jersey Client API is recommended. The example is included in test package.
The XML message format follows OAI-PMH protocol as far as XML response and error messages are concerned. In Y1 the service implements three methods: to retrieve a list of
available analysis data on projects' releases, to retrieve a single project's release analysis results and to identify the repository. Those methods also support compression (gzip).
The XML message formats follow the OAI-PMH protocol, however the API will be further developed in Y2 to be better aligned with OAI-PMH standard.
By default the web service is available at the following context:
http://localhost:8080/markos-code-analyser-data-retrieval/
The RESTful methods are available at context:
http://localhost:8080/markos-code-analyser-data-retrieval/rest/dataretrieval/
Below there is a brief description of available methods.
II. Service interface of markos-code-analyser-data-retrieval
1. Retrieving a list of projects.
Method retrieves a list of projects available in the code analyser database, analysed in a given time frame.
1.1 Method's call:
- URL: http://<base_url>/markos-code-analyser-data-retrieval/rest/dataretrieval/listRecords/{dateFrom}/{dateTo}
1.2 Parameters:
- dateFrom (String value pattern is YYYY-MM-DD)
- dateTo (String value pattern is YYYY-MM-DD)
1.3 Sample XML response:
<?xml version='1.0' encoding='UTF-8'?>
<OAI-PMH xmlns='http://www.openarchives.org/OAI/2.0/'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.openarchives.org/OAI/2.0/
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd'>
<responseDate>2002-06-01T19:20:30Z</responseDate>
<request verb="ListRecords" metadataPrefix=""></request>
<ListRecords>
<record>
<header>
<identifier>1/234</identifier>
<datestamp>2013-06-18T00:00Z</datestamp>
<setSpec/>
</header>
<metadata>
<project-metadata xmlns="http://www.markosproject.eu/ca/project-metadata/SP3/" xsi:schemaLocation="http://www.markosproject.eu/ca/project-metadata/SP3/ http://abelia.man.poznan.pl/markos/project-metadata_schema-SP3.xsd">
<project_id>1</project_id>
<release_id>234</release_id>
<project_name>apache abdera</project_name>
<release_name>1.7.1</release_name>
<latest_analysis_date>2013-06-18T00:00Z</latest_analysis_date>
</project-metadata>
</metadata>
<about/>
</record>
</ListRecords>
</OAI-PMH>
The returned project metadata is defined in the following XSD schema: http://abelia.man.poznan.pl/markos/project-metadata_schema-SP3.xsd
1.4 Sample XML error response:
Sample error message which is aligned with OAI-PMH protocol:
<?xml version='1.0' encoding='UTF-8'?>
<OAI-PMH xmlns='http://www.openarchives.org/OAI/2.0/'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.openarchives.org/OAI/2.0/
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd'>
<responseDate></responseDate>
<request verb="ListRecords" identifier=""></request>
<error code="">Sample error message goes in here..</error>
</OAI-PMH>
The code attribute of error element can be:
- "extractionError" for internal XML processing errors
- "inputParamsInvalid" for invalid input params.
2. Retrieving a single project analysis data.
Method retrieves a single project analysis data.
2.1 Method's call:
- URL: http://<base_url>/markos-code-analyser-data-retrieval/rest/dataretrieval/getRecord/{project_id}/{project_release_id}
2.2 Parameters:
- project_id (project ID)
- project_release_id (project release ID)
2.3 Sample XML response for apache accumulo 1.3.6 project data:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<OAI-PMH xmlns="http://www.openarchives.org/OAI/2.0/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd">
<responseDate>2013-07-10T13:29Z</responseDate>
<request identifier="1/234" metadataPrefix="markos_ca_db" verb="GetRecord"/>
<GetRecord>
<record>
<header>
<identifier>1/234</identifier>
<datestamp>2013-07-10T13:29Z</datestamp>
</header>
<metadata>
<project_analysis_data
xmlns="http://www.markosproject.eu/ca/project-analysis-data-schema/SP3/"
xsi:schemaLocation="http://www.markosproject.eu/ca/project-analysis-data-schema/SP3/
http://abelia.man.poznan.pl/markos/markos_code_analyser_db_schema-SP3.xsd">
<!-- content aligned with /markos-code-analyser-data-retrieval/src/main/resources/markos_code_analyser_db_schema.xsd schema -->
...
</project_analysis_data>
</metadata>
</record>
</GetRecord>
</OAI-PMH>
The format of Project Analysis Results is defined in XSD Schema at the following location:
http://abelia.man.poznan.pl/markos/markos_code_analyser_db_schema-SP3.xsd
2.4 Sample XML error response:
Sample error message which is aligned with OAI-PMH protocol:
<?xml version='1.0' encoding='UTF-8'?>
<OAI-PMH xmlns='http://www.openarchives.org/OAI/2.0/'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.openarchives.org/OAI/2.0/
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd'>
<responseDate></responseDate>
<request verb="getRecord" identifier=""></request>
<error code="">Some error message</error>
</OAI-PMH>
The code attribute of error element can have following values:
- "inputParamsInvalid" for invalid input params
- "extractionError" for XML processing errors
- "idDoesNotExist" when a requested project analysis data is not available.
3. Retrieving repository identity information
A method to retrieve XML formated information about the repository.
3.1 Method's call:
- URL: http://<base_url>/markos-code-analyser-data-retrieval/rest/dataretrieval/identify
3.2 Parameters:
- no parameters
3.3 Sample XML response:
<?xml version='1.0' encoding='UTF-8'?>
<OAI-PMH xmlns='http://www.openarchives.org/OAI/2.0/'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.openarchives.org/OAI/2.0/
http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd'>
<responseDate>2013-07-11T12:39Z</responseDate>
<request verb='Identify'>http://markosproject.eu/codeanalyser_dataretrieval</request>
<Identify>
<repositoryName>Code Analyser Projects' Analysis Repository</repositoryName>
<baseURL>http://markosproject.eu</baseURL>
<protocolVersion>2.0</protocolVersion>
<adminEmail/>
<earliestDatestamp>2013-06-18</earliestDatestamp>
<deletedRecord>no</deletedRecord>
<granularity>YYYY-MM-DD</granularity>
<compression>gzip</compression>
<description/>
</Identify>
</OAI-PMH>
TROUBLESHOOTING:
In case of any issues please contact:
Pawel Kedziora, PSNC
kedziora@man.poznan.pl
