Summary:
While working with
Ontotext KIM you may encounter some difficulties or you may want to do some simple common tasks, so I have created this FAQ:
1. Problems starting KIM
KIM incorporates a semantic repository - a storage and inference layer software called
OWLIM (see below). It is not a relative database, we could call it a knowledge database, but still a database. It has locks, transactions and thus when you forcibly should down the database, you will get some complaints that something went wrong.
To avoid this you should always use:
startKIM.bat and
stopKIM.bat to start/stop the KIM server and the KIM GATE UI (
\bin\startKIMGate.bat). Problems are usually related to the
lock(or
stack file) in
\context\default\populated folder and you need to delete this file manually. This file tells
OWLIM that the previous instance of
OWLIM did shutdown correctly. The
populated folder is where all data and index files are stored. If you do not keep something important in the database you may delete all files in the
\context\default\populated folder. This will force OWLIM to reload all
nt and
owl files, create a new cache and thus fix some problems. It is something like a Windows reinstall. Keep in mind that clearing your entire
populated folder will make KIM load much slower in order to rebuild everything.
2. I do not see my annotations
Suppose you have a Jape file and you use it KIM GATE UI(
\bin\startKIMGate.bat) and you do not see your annotation in the "Annotation Sets" in GATE. If you are sure that this annotation should be visible the problem might be in the KIM GATE pipeline. The pipeline has two resources "Instance Generator" and "Annotation Cleaner". The "Instance Generator" is very important resource in KIM and part of its jobs is to clear unrecognized and temp annotations. The "Annotation Cleaner" also does a similar job. To make the "Instance Generator" aware of your annotation you need to add it to a white list in
\config\nerc.properties in
com.ontotext.kim.KIMConstants.IE_ANN_TYPES. The second solution is to temporally disable these two GATE resources from the pipeline. This can be done when you click on the KIM application and click a resource in "Selected processing resources".
The "Instance Generator" is the one who makes the connection between your annotation and the entities in the semantic repository (stored in the
OWLIM database).
3. What is the difference between "inst" and "class"?
Generally the "inst" feature holds the URI of an entity. If the entity has been recognized by the semantic gazetteer (KIM Gazetteer), it is an existing entity in the semantic repository with a specific URI. If, on the other side, it has been extracted with the help of some Jape rules for example, the entity does not exist so only a class feature should be provided. Later, if the Instance Generator PR is a part of the pipeline, it will create a unique instance URI for this entity and put it in the semantic repository.
4. How to add a new OWL file?
1. You can use a tool in the
\bin\tools called "toolRdfImport.bat(.sh)" which requires a folder as a parameter. The tool will import all files in the specified folder.
d:\kim\bin\tools>toolrdfimport c:\test\owl
Every time you add a new property you can just use this tool over the same file. Check the documentation
here.
There is also another tool called "toolRdfUpdate.bat" which can make a diff between two files and then applies the changes - both add and remove. With "toolRdfImport.bat" you can only add. Unfortunately "toolRdfUpdate.bat" is not that easy to use.
2. Usually all knowledge-base files reside in "\kim\context\default\kb" and OWL files are in the subfolder "owl". The second option is to edit the file
\config\owlim.ttl. As the name tells this file configures the
OWLIM database. You need to add a new line in both "imports" and "defaultNS". The first line points to your OWL file and the one in "defaultNS" must be at same row number as in "imports". Every line in "imports" has a corresponding line in "defaultNS". Both sections must have the same row number count (obviously). Then you need to delete the contents of your
\context\default\populated folder and restart KIM. Keep in mind that by deleting
\context\default\populated you will lose all data loaded through KIM GATE UI or the "
\bin\tools\toolConsolePopulate ". You will also need to wait longer for KIM to start than usual, so that OWLIM indexes and cache are built again.
5. Troubleshooting the KIM server communication
Usually communication is done through RMI or Web Services.
The most important config properties when using RMI are:
5.1. Changing the Java Policy
The JVM that KIM Server uses must be configured so that it allows calls on the ports KIM Server exposes. This is done by editing permissions in:
(JRE) /$JRE/lib/security/java.policy
(JDK) /$JDK/jre/lib/security/java.policy
The following line in the file should be modified so it allows connecting to the ports specified from an outer machine:
// allows anyone to listen on un-privileged ports
to
// allows anyone to listen, connect or accept connections on un-privileged ports
5.2. Setting up your external IP address
You get message like these:
WARN: It appears that the remote KIM RMI server, expected at XXX.XXX.XXX.XXX reported the wrong endpoint socket: ChannelIfaceImpl_Stub[UnicastRef [liveRef: [endpoint:[127.0.0.1:40695](remote),objID:
WARN: The connection is likely to fail. If it does, alert the server administrators and attach this message.
This means that the RMI do not know on which IP to listen for your incoming connections. This usually happens on machines with more than one IP address and it depends by the RMI implementation for each JVM. You need to explicitly state the IP address on which you expect to find the KIM server in config/install.properties:
com.ontotext.kim.KIMConstants.RMI_HOST=192.168.121.139
This specifies a visible/outer IP for the server. Java RMI clients will try to find the KIM Server at that IP address, so it must be the same as the address used in GetService.from(IP, port) in the client code.
Usually on a Linux systems with more than one IP address you need to set the address that you are going to use to access the KIM server in \config\install.properties.
The next version KIM 3.0 will provide services through
JMS. You can find a .NET demo utilizing the Web Services
here.
6. How to develop Jape rules easier
A JAPE Eclipse plug-in with code-complete and syntax high-lightening is definitely a good idea, but it is not available!
Each JAPE rule is being converted to pure JAVA code.
If you make a mistake in the Java part (there might be no JAVA code) of your JAPE rule you will get an exception and you will see the generated Java code. You could copy paste this code into Eclipse and complete it comfortably. You may need to cause an exception on purpose from the very beginning to get the that code. Then when done you can paste the needed part back to the Java part of your Jape rule. Once again - Jape rules might contain Java code thanks to the GATE API or they might not. Let's illustrate what I mean:
Phase:
NameInput: Token Lookup TempDate
Options: control = appelt
Rule: EarlyDate
// early in 2002// in early 2002( ({Token.
string == early
}|
{Token.
string == late
} ) ({Token.
string ==
"in"} )?
({TempDate
}|
( {Lookup.
majorType == time_modifier
} {Lookup.
majorType == date_unit
} ) )):date
-->
{//removes TempDate annotation, gets the rule feature and adds a new TempDate annotationgate.
AnnotationSet date =
(gate.
AnnotationSet)bindings.
get("date");
gate.
Annotation dateAnn =
(gate.
Annotation)date.
iterator().
next();
gate.
FeatureMap features = Factory.
newFeatureMap();
features.
put("rule", dateAnn.
getFeatures().
get("rule"));
features.
put("rule2",
"EarlyDate");
annotations.
add(date.
firstNode(), date.
lastNode(),
"TempDate",
features
);
annotations.
removeAll(date
);
}
And the Java code I got by causing a compiler exception by putting some random symbols(here removed):
package japeactionclasses;
import java.io.*;import java.util.*;import gate.*;import gate.jape.*;import gate.creole.ontology.Ontology;import gate.annotation.*;import gate.util.*; public class NameEarlyDateActionClass314
implements java.
io.
Serializable, RhsAction
{ public void doit
(Document doc, java.
util.
Map bindings,
AnnotationSet annotations,
AnnotationSet inputAS, AnnotationSet outputAS,
Ontology ontology
) { {//removes TempDate annotation, gets the rule feature and adds a new TempDate annotation gate.
AnnotationSet date =
(gate.
AnnotationSet)bindings.
get("date");
gate.
Annotation dateAnn =
(gate.
Annotation)date.
iterator().
next();
gate.
FeatureMap features = Factory.
newFeatureMap();
features.
put("rule", dateAnn.
getFeatures().
get("rule"));
features.
put("rule2",
"EarlyDate");
annotations.
add(date.
firstNode(), date.
lastNode(),
"TempDate",
features
);
annotations.
removeAll(date
);
}}}
This Java code sample should compile in Eclipse without any problem (after you add the GATE libraries). You can download these two files from:
http://code.google.com/p/kimnetdemos/source/browse/#svn/trunk/Jape-template. Also keep in mind that you do not control the import section and thus you should use non-GATE classes with their fully qualified names.
OWLIM: It not only stores knowledge, but it also expands this knowledge based on the already stored knowledge.
OWLIM also stores the rules that are used to infer new knowledge from the old one.
OWLIM is striving to be the fastest storage and inference layer database on the market and it would backup its claims if you download it for a test drive.
I will be adding more tips while I dig deeper into the
Ontotext KIM platform
and
Sheffield GATE.
This FAQ is not officially provided/approved/supported by
Ontotext or the GATE team.
Quick links:
The Semantic Annotation Workflow - KIM part 10
KIM Multi-threaded Clustered Client Application - KIM part 9
Gazetteers - KIM/GATE part 7
Strict Rules vs Machine Learning - KIM part 6
Tips and Tricks - KIM part 5
Using a Gate application - KIM part 4
Gate tutorial - KIM part 3
Using KIM from .NET - KIM part 2
Getting Started - KIM part 1
Installation - KIM part 0
Click to enlarge
