MajorTom-Server

1. How to Install MajorToM-Server

To use MaJorToM-Server, you must have a Tomcat 7 with the manager app (which is delivered with the server) installed.

1.1. Prepare the tomcat

Download the tomcat application and unpack the archive. You can find the current version at http://tomcat.apache.org/ .

After downloading, specify a user in TOMCATROOT/conf/tomcat-users.xml e.g.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="manager-gui"/>
  <role rolename="admin-gui"/>
  <user username="username" password="password" roles="manager-gui, admin-gui"/>
</tomcat-users>

This user is able to deploy a web application.

After that start the tomcat server with

TOMCATROOT/bin/catalina.sh start

Visit http://localhost:8080 and the tomcat start page should be visible.

1.2. Checking out the Source Code

The MaJorToM-Server development team uses mercurial as source control management tool. Install mercurial as described on their website http://mercurial.selenic.com/ .

Check out the source code with:

hg clone https://majortom-server.googlecode.com/hg/ majortom-server

To select a specific version you have to switch to a version branch. The default branch is the current development branch. Branches beginning with V are version branches, e.g. V1_0_0 .

To switch a branch use the following command

hg update VERSION

For a list of all available branches use the command:

hg branches

1.3. Configuring the MaJorToM-Server

No matter which way you chose to deploy the MaJorToM-Server, some configuration is necessary prior to deployment.

First, go to SOURCEROOT/src/main/resources and rename the file server.properties.sample to server.properties. Open the file with a text editor and modify the values as shown below.

1.3.1. Cache configuration

The MaJorToM-Server has a built-in caching mechanism that stores the once executed queries and returns the cached values whenever a cached query is executed again. The default is in-memory caching. To enable caching with a Redis store, you can change the class property to de.topicmapslab.majortom.server.cache.RedisCache.

Note	You can disable caching if you just leave the class property blank.

1.3.2. Redis configuration

When you want to use a Redis store for caching, you must configure the hostname and storeId properties. If your Redis store requires authentification, you must as well configure the password property.

1.3.3. Authentification store configuration

The MaJorToM-Server needs a place to store the information about usernames and passwords. The default settings make use of an HSQL store. All you have to configure is the db.jdbcurl property which points to the place of the HSQL file.

Note	You may as well use other stores as long as there is a hibernate dialect available. Please read the hibernate documentation for more info.

1.4. Installing with Maven

Before installing from source, you will have to install Maven 3.

1.4.1. Prepare the deployment

Maven provides plugins, which deploy a web application directly into a tomcat instance. To use this feature it is necessary to modify the pom.xml of the MaJorToM-Server project. Look for the following entry and add the url to your tomcat instance.

        <properties>
                <spring.version>3.0.5.RELEASE</spring.version>
                <tmql.version>3.1.0-SNAPSHOT</tmql.version>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
                <server.url>http://localhost:8080</server.url>
        </properties>

The login data of the server is stored in the settings.xml of Maven. You can find it at:

HOME/.m2

If you don’t find it there you might find it at

HOME/.m2/conf

If you don’t have a settings.xml copy the following, otherwise just add the server part to your file:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers>
          <server>
                <id>mt-server</id>
                <username>username</username>
                <password>password</password>
          </server>
  </servers>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

After that you can deploy the server with

mvn tomcat:deploy

You will find the admin interface at

http://localhost:8080/majortom-server/admin/

If you deploy to another server than the localhost you need to adapt the host and port.

ATTENTION: You must have the trailing / or the admin page won’t be found.

1.5. Creating and installing a WAR-File

If you don’t want to deploy the MaJorToM-Server with Maven, you may as well create a traditional WAR-File (e.g. with Eclipse) and deploy it as you deploy any other WAR-File.

2. The Administration Page

2.1. Log-in and create users

At it’s first start, the server creates two default users.

The first one, the default administrator, is the user admin with the password sEcReT. You should modify the password as soon as possible.

To modify the password visit:

SERVER/majortom-server/admin/

and click on Show Users.

Edit admin and enter a new password. After pressing submit the new password is stored.

Note	The second default user is named Hans. He is there just so you have an user with API-Key to play around without creating a new one. He may disappear in future releases.

To create a new user, use Add User below the user table and enter the user data.

The password is stored as a hash, so intruders can’t read the real password.

Note	Users don’t have an API-Key upon creation. The admin user must create one in order to permit access to the topic maps for the user.

2.2. Configure Database Connection

The server is able to use the DB-backend of MaJorToM, but only one database at a time and only a POSTGRES database.

Configure the connection in the admin interface and after that create a new topic map with deselected in memory checkbox.

2.3. Create a Topic Map

To create a Topic Map, clock on Create a Topic Map in the admin interface.

The Topic Map needs a baselocator, which must be an URI and will be used to identify the Topic Map.

The In Memory checkbox indicates whether the topic map is stored in-memory or in the configured database (if none is configured an exception is thrown).

The Local file path field can be used to load a topic map which is already in a directory on the server. A directory can be entered to load all topic map files in the directory into the new topic map.

To get a better loading performance the user can enter an Initial Capacity of all the maps used in the InMemoryStore. This applies only for in-memory topic maps.

Last but not least, the Topic Map File field is used to upload an xtm or ctm file, which will be loaded after the creation of the topic map.

Note	Loading of files is done in background. Although the server indicates to be finished with creating the Topic Map, it may not be loaded already.

2.4. List of Topic Maps

In the list of Topic Maps the following operations are available:

delete deletes a Topic Map from the Topic Map System including all data
clean removes the content of the Topic Map. An empty Topic Map remains.
close closes the Topic Map. This is only useful when using database Topic Maps. The Topic Map won’t be available by the server but the data remains in the database.

3. MajorToM HTTP API

The MaJorToM-Server provides an URL-based API.

3.1. The result format

All queries to the API result in a JSON-object which has the following form:

{code : "0", msg : "OK", data : [] }

The fields in detail: * The code indicates the success of the query. 1 means something went wrong, 0 indicates the query was a success. * The msg contains a message, which explains an error. * The data contains the result values, e.g. the JTMQR object of a TMQL query

Note	For a detailed description of the JTMQR format please look at http://code.google.com/p/tmql/wiki/JTMQR

To identify the different Topic Maps the MaJorToM-Server uses an unique id of the Topic Map. The unique id is the MD5 checksum of the base locator.

The following variables will be used to shorten the URL in the following API documentation:

SERVER the url for the server e.g. http://majortom.topicmapslab.de
TMID for the unique Topic Map id

Every API call needs a parameter apikey which is unique to given for every user!

3.2. Get the list of all available Topic Maps

To get an overview on the available Topic Maps on the server, you can use the following URL:

SERVER/tm/topicmaps

You need only one parameter:

Name	Type	Description
apikey	String	the apikey for the user

3.3. Get the ID of a Topic Map

Instead of calculating the unique id you can ask the server for it. Use the following URL with a GET request:

SERVER/tm/resolvetm

This URL needs the following parameters:

Name	Type	Description
bl	String	Baselocator to resolve
apikey	String	the apikey for the user

3.4. Execute TMQL Queries

Executing TMQL queries is easy. Just use the following URL:

SERVER/tm/tmql/TMID

This URL needs the following parameter (POST and GET are supported, we strongly encourage you to use a POST request here):

Name	Type	Description
query	String	tmql query
apikey	String	the apikey for the user
jtmqr	String	1 or 2; the version of the JTMQR syntax for the query results

The JTMQR result is stored inside the data field of the query result.

Warning

The results will be created using IResultSet.toJTMQR. Do not use "USE JTMQR" inside the query!

Note	Update Queries are also supported.

3.5. Execute a SPARQL query

Similar to TMQL queries, you may execute SPARQL queries with the following URL:

SERVER/tm/sparql/TMID

This URL needs the following parameter (POST and GET are supported, we strongly encourage you to use a POST request here):

Name	Type	Description
query	String	sparql query
apikey	String	the apikey for the user

3.6. Search the fulltext index

At Topic Map loading time, a fulltext index (based on Beru and Lucene) is created. Thus, you can do fulltext querying with the usual Lucene wuery syntax with the following URL:

SERVER/tm/beru/TMID

This URL needs the following parameter (POST and GET are supported):

Name	Type	Description
query	String	sparql query
apikey	String	the apikey for the user

3.7. Get a Serialization of a Topic Map

To serialize a topic map just use the URL:

SERVER/tm/xtm/TMID

for an XTM serialization or

SERVER/tm/ctm/TMID

for an CTM serialization.

The parameters are (both, POST and GET requests are allowed):

Name	Type	Description
apikey	String	the apikey for the user

The serialization will be the result in the stream.

3.8. Clear the cache for a Topic Map

To clear the cache of a topic map use the following URL:

SERVER/tm/clearcache/TMID

The parameters are (both, POST and GET requests are allowed):

Name	Type	Description
apikey	String	the apikey for the user

3.9. Reindex a Topic Map

To reindex for the fulltext search a topic map use the following URL:

SERVER/tm/clearindex/TMID

The parameters are (both, POST and GET requests are allowed):

Name	Type	Description
apikey	String	the apikey for the user