<?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>
To use MaJorToM-Server, you must have a Tomcat 7 with the manager app (which is delivered with the server) installed.
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.
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
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.
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. |
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.
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. |
Before installing from source, you will have to install Maven 3.
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.
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.
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. |
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.
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. |
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.
The MaJorToM-Server provides an URL-based API.
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!
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 |
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 |
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. |
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 |
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 |
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.
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 |
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 |