Page History

Apache OODT XMLPS is an extensible, configurable product and profile server that easily exposes DBMS-backed repositories and catalogs, respectively, over a REST-ful interface.

XMLPS grew out of the EDRN Informatics Center and its EDRN Resource Network Exchange (ERNE) project.

Here's a quick step guide to getting XMLPS up and running on your project.

Get and Build Apache OODT Web-Grid

...

To get started with Apache OODT XMLPS, you'll need to install Apache OODT Web Grid.

1. svn co latest OODT from trunk
2. mvn install from OODT/trunk top levelgit clone https://git-wip-us.apache.org/repos/asf/oodt.git
3. cd grid
4. mvn package war:war install (builds target/web-grid-0.11-SNAPSHOT.war)

You're done here for now, let's go grab Apache Tomcat.

Grab Apache Tomcat and install it

Grab Apache Tomcat. I prefer the 5.5.x series. For those 6.x and 7.x fanboys, instructions will likely be similar.

1. curl -O http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.36/bin/apache-tomcat-5.5.36.tar.gz
2. mv apache-tomcat-5.5.36.tar.gz /usr/local
3. cd /usr/local ; tar xzvf apache-tomcat-5.5.36.tar.gz
4. ln -s /usr/local/apache-tomcat-5.5.36 tomcat5
5. edit /usr/local/tomcat5/conf/tomcat-users.xml and add a new user "xmlps" with password "secret" with the roles="manager,admin"

You're done for now with the Tomcat installation. Time to layer the web-grid substrate on top of it.

Layering Apache OODT Web Grid on top of Tomcat

1. copy web-grid-0.5.war from the target directory from your built Web-Grid to /usr/local/tomcat5/webapps/grid.war (yes rename it, you'll thank me later)

   Warning
   title Warning
   Make sure Tomcat isn't running until the guide says for you to turn it on. Tomcat doesn't like you messing with its webapp and work directories.

Building and Installing XMLPS

1. git clone https://git-wip-us.apache.org/repos/asf/oodt.git
2. cd xmlps
3. mvn install
4. cd ../xmlps
5. mvn package assembly:assembly (builds target/oodt-xmlps-0.5-with-dependencies.jar)
6. create test deploy area, e.g., /usr/local/xmlpstest xmlps and copy oodt-xmlps-0.5-with-dependencies.jar to it
7. copy example conf files out of xmlps/src/main/conf (example.db.properties and example-ps.xml) into test area
8. modify examples for your database (I used a local postgres instance and I created a simple mapping file with 2 fields, one dynamic and one constant that queried 1 database)
9. copy WAR file to $TOMCAT_HOME/webapps/grid.war
10. /usr/local/xmlps

Set up a database

Let's assume you have installed MySQL. There are plenty of guides out there to do so (including the one I just linked to) for specific operating systems, etc. So assuming that you have MySQL already installed, let's create a quick database and sample schema and user.

1. Create a MySQL database with user xmlps and password xmlps and add some sample data.

   Code Block
   sql sql
   CREATE DATABASE xmlps; GRANT ALL PRIVILEGES ON xmlps.* TO 'xmlps'@'localhost' IDENTIFIED BY 'xmlps'; GRANT ALL PRIVILEGES ON xmlps.* TO 'xmlps'@'%' IDENTIFIED BY 'xmlps';

2. Log on to MySQL with user xmlps

   No Format
   mysql -u xmlps xmlps -p

   (enter password "xmlps")

3. Create a simple data product schema

   Code Block
   sql sql
   CREATE TABLE products (product_id int auto_increment NOT NULL PRIMARY KEY, product_name varchar(255));

4. INSERT 2 rows of data into the table

   Code Block
   sql sql
   INSERT INTO products (product_name) VALUES ('Test1'); INSERT INTO products (product_name) VALUES ('Test2');

Download the MySQL connector JAR and install it

You can grab version 5 of the MySQL JAR connector and it should work fine. If it doesn't, grab one of the appropriate versions for your MySQL DB.

1. curl -O http://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.6/mysql-connector-java-5.1.6.jar
   Now you have to unzip grid.war that you installed in Tomcat, and install the JDBC driver to its WEB-INF/lib directory
2. cd /usr/local/tomcat5/webapps/ ; unzip grid.war
   Now copy the JDBC jar file to the unzipped grid's WEB-INF/lib directory
3. cp mysql-connector-java-5.1.6.jar /usr/local/tomcat5/grid/WEB-INF/lib

Configure XMLPS to talk to your MySQL DB

Now that everything is installed, and that you have a DB, you'll need to configure XMLPS to talk to your backend MySQL db. The first step is to configure the DB connection.

1. Edit /usr/local/xmlps/example.db.properties.

   Code Block

   # Licensed to the Apache Software Foundation (ASF) under one or more # contributor license agreements. See the NOTICE file distributed with # this work for additional information regarding copyright ownership. # The ASF licenses this file to You under the Apache License, Version 2.0 # (the "License"); you may not use this file except in compliance with # the License. You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # Example data source configuration file xmlps.datasource.jdbc.url=jdbc:mysql://localhost:3306/xmlps?autoReconnect=true xmlps.datasource.jdbc.user=xmlps xmlps.datasource.jdbc.pass=xmlps xmlps.datasource.jdbc.driver=com.mysql.jdbc.Driver

2. Expose the underlying data from the DB by editing the /usr/local/xmlps/example-ps.xml. We're going to rename the product_id field to "id" and the product_name field to "name" and add a constant field representing the data quality (called "quality_flag"), giving it the value "sample" to indicate this is just a test.

   Code Block
   xml xml
   <?xml version="1.0" encoding="UTF-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <oodt:xmlps xmlns:oodt="http://incubator.apache.org/oodt/0.1-incubating" name="My Query Handler" id="myqueryhandler"> <tables default="products"> </tables> <field type="dynamic" name="id" dbname="product_id" /> <field type="dynamic" name="name" dbname="product_name"/> <field type="constant" name="quality_flag" value="sample" /> </oodt:xmlps>

Now XMLPS is configured to talk to the DB and to map the values and names from the underlying database to a common language (id, name and quality_flag rather than product_id and product_name in relational database ville).

Startup and visit your Tomcat server

OK it's actually time to start Tomcat.

1. cd /usr/local/tomcat5/bin ; ./startup.sh
   Now visit http://localhost:8080/grid/^{Image Removed} Image Added
2. Click the Configure tab and enter the default Web-Grid password (you can find it here on slide 25) – you'll end up on a screen like the below.
   Image Added
3. Scroll down and configure web-grid after logging in to use XMLPS handler, and to reference your JDBC XMLPS jar file (that you copy into in /usr/local/xmlps
   Image Added
   Image Added
4. Add the 2 properties ("org.apache.oodt.xmlps.xml.mapFilePath" set to /usr/local/xmlpstest), and to reference XMLPS jar file in xmlps/example-ps.xml and "org.apache.oodt.xmlps.xml.dbPropFilePath" set to /usr/local/xmlpstestxmlps/example.db.properties). This binds your XMLPS to the configuration files that you edited previously to connect to the DB and unlock its information.
   Image Added

Issue a Query against XMLPS

Now that you have XMLPS and Web-Grid configured, Tomcat running, etc., it's time to issue a query against it! Try a query for name=Test2 (should only return the 2nd product):

1. try a query at:

   curl

   http://localhost:8080/grid/prod?q=

   ^{Image Removed}

   RETURN%3Did+AND+RETURN%3Dname+AND+name=%27Test2%27

   No Format
   2 Test2$

2. you can also tell it to return other fields, like the constant field tag

3. curl http://localhost:8080/grid/prod?q=RETURN%3Did+AND+RETURN%3Dname+AND+name=%27Test2%27+AND+RETURN%3Dquality_flag

   No Format
   2 Test2 sample$

That's it! You're up and running!

Other Relevant Reading

1. Mattmann's original guide for XMLPS (12 steps)
2. Mailing list conversation/chatter about installing XMLPS