You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by rw...@apache.org on 2013/08/29 14:57:56 UTC

svn commit: r1518628 - in /stanbol/trunk/enhancement-engines: ./ topic/api/ topic/api/src/ topic/api/src/main/ topic/api/src/main/java/ topic/api/src/main/java/org/ topic/api/src/main/java/org/apache/ topic/api/src/main/java/org/apache/stanbol/ topic/a...

Author: rwesten
Date: Thu Aug 29 12:57:55 2013
New Revision: 1518628

URL: http://svn.apache.org/r1518628
Log:
STANBOL-1142: applied the patch provided by Sebastian Schaffert. Also changed TopicClassifier#getChainNames() to no longer throw an ChainException. Implementation should just silently ignore Chains that cause an exception.

Added:
    stanbol/trunk/enhancement-engines/topic/api/   (with props)
    stanbol/trunk/enhancement-engines/topic/api/pom.xml
    stanbol/trunk/enhancement-engines/topic/api/src/
    stanbol/trunk/enhancement-engines/topic/api/src/main/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/Batch.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/BatchProcessor.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassificationReport.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassifierException.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicClassifier.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicSuggestion.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/Example.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSet.java
    stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSetException.java
Removed:
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/Batch.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/BatchProcessor.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/ClassificationReport.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/ClassifierException.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/TopicClassifier.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/TopicSuggestion.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/Example.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/TrainingSet.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/TrainingSetException.java
Modified:
    stanbol/trunk/enhancement-engines/pom.xml
    stanbol/trunk/enhancement-engines/topic/engine/pom.xml
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/engine/topic/TopicClassificationEngine.java
    stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/SolrTrainingSet.java
    stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TopicEngineTest.java
    stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TrainingSetTest.java
    stanbol/trunk/enhancement-engines/topic/web/pom.xml
    stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicClassifierRootResource.java
    stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicModelResource.java

Modified: stanbol/trunk/enhancement-engines/pom.xml
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/pom.xml?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/pom.xml (original)
+++ stanbol/trunk/enhancement-engines/pom.xml Thu Aug 29 12:57:55 2013
@@ -76,10 +76,14 @@
     <module>entitylinking</module>
     <module>entityhublinking</module>
     <module>entitytagging</module>
+    <!-- fast EntityLinking using Lucene FST -->
+    <!-- TODO: not yet included in the default build -->
+    <!-- <module>lucenefstlinking</module> -->
     <!-- deprecated -->
     <module>keywordextraction</module>
 
 	  <!-- Categorization -->
+    <module>topic/api</module>
     <module>topic/engine</module>
     <module>topic/web</module>
 
@@ -105,7 +109,6 @@
     <module>geonames</module> <!-- http://geonames.org -->
     <module>opencalais</module> <!-- http://opencalais.com/ -->
     <module>zemanta</module> <!-- htt://zemanta.com -->
-  
   </modules>
 
   <build>

Propchange: stanbol/trunk/enhancement-engines/topic/api/
------------------------------------------------------------------------------
--- svn:ignore (added)
+++ svn:ignore Thu Aug 29 12:57:55 2013
@@ -0,0 +1,7 @@
+target
+
+.project
+
+.classpath
+
+.settings

Added: stanbol/trunk/enhancement-engines/topic/api/pom.xml
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/pom.xml?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/pom.xml (added)
+++ stanbol/trunk/enhancement-engines/topic/api/pom.xml Thu Aug 29 12:57:55 2013
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.apache.stanbol</groupId>
+        <artifactId>apache-stanbol-enhancement-engines</artifactId>
+        <version>0.10.1-SNAPSHOT</version>
+        <relativePath>../..</relativePath>
+    </parent>
+
+    <groupId>org.apache.stanbol</groupId>
+    <artifactId>org.apache.stanbol.enhancer.engine.topic.api</artifactId>
+    <version>0.10.1-SNAPSHOT</version>
+    <packaging>bundle</packaging>
+
+    <name>Apache Stanbol Enhancement Engine : Topic Classification (API)</name>
+    <description>
+        Implementation of an annotation engine that links the content item
+        to a set of possible categories from a dedicated Solr index using
+        MoreLikeThis queries.
+
+        The classification can be either applied to a complete document
+        (text in a given language) which is the default behavior or to a
+        specific portion of the text (using a TextAnnotation).
+    </description>
+
+    <inceptionYear>2010</inceptionYear>
+
+    <scm>
+        <connection>
+            scm:svn:http://svn.apache.org/repos/asf/stanbol/trunk/enhancement-engines/topic/engine/
+        </connection>
+        <developerConnection>
+            scm:svn:https://svn.apache.org/repos/asf/stanbol/trunk/enhancement-engines/topic/engine/
+        </developerConnection>
+        <url>http://stanbol.apache.org/</url>
+    </scm>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.servicemix.tooling</groupId>
+                <artifactId>depends-maven-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.felix</groupId>
+                <artifactId>maven-bundle-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <instructions>
+                        <Import-Package>
+                            org.apache.stanbol.enhancer.topic.api,
+                            org.apache.stanbol.enhancer.topic.api.training,
+                            *
+                        </Import-Package>
+                        <Export-Package>
+                            org.apache.stanbol.enhancer.topic.api;version=${project.version},
+                            org.apache.stanbol.enhancer.topic.api.training;version=${project.version}
+                        </Export-Package>
+                    </instructions>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.rat</groupId>
+                <artifactId>apache-rat-plugin</artifactId>
+                <configuration>
+                    <excludes>
+                        <!-- AL20 licensed files. See src/main/resources/README -->
+                        <exclude>src/main/resources/install-config/default-topic-model.solrindex.ref</exclude>
+                        <exclude>src/license/THIRD-PARTY.properties</exclude>
+                    </excludes>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>commons-lang</groupId>
+            <artifactId>commons-lang</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.clerezza</groupId>
+            <artifactId>rdf.core</artifactId>
+        </dependency>
+
+    </dependencies>
+    
+</project>
\ No newline at end of file

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/Batch.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/Batch.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/Batch.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/Batch.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Container data transfer object to fetch partial results over a query results one batch at a time.
+ * 
+ * @param <T>
+ *            the type of the items to batch over.
+ */
+public class Batch<T> implements Serializable {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Boolean marker set by the backend to tell the caller that it can expect new items by issuing the same
+     * query by passing the companion offset marker.
+     */
+    public final boolean hasMore;
+
+    /**
+     * Marker value that the caller can pass to the dataset to fetch the next batch and perform efficient
+     * server side batching.
+     * 
+     * This value should refer to an indexed field with unique values such as a primary key or a random uuid
+     * (good for shuffling the example in arbitrary order). The samples return in the batches should be sorted
+     * according to this field so that the server can perform efficient range queries that are guaranteed to
+     * return no duplicate results across batches.
+     */
+    public final Object nextOffset;
+
+    public final List<T> items;
+
+    public Batch(List<T> items, boolean hasMore, Object nextOffset) {
+        this.items = items;
+        this.hasMore = hasMore;
+        this.nextOffset = nextOffset;
+    }
+
+    /**
+     * Helper method to return a first empty batch to bootstrap an iteration loop.
+     */
+    public static <T2> Batch<T2> emtpyBatch(Class<T2> clazz) {
+        return new Batch<T2>(new ArrayList<T2>(), true, null);
+    }
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/BatchProcessor.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/BatchProcessor.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/BatchProcessor.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/BatchProcessor.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,27 @@
+/*
+* 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.
+*/
+package org.apache.stanbol.enhancer.topic.api;
+
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
+
+import java.util.List;
+
+public interface BatchProcessor<T> {
+
+    int process(List<T> batch) throws ClassifierException, TrainingSetException;
+
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassificationReport.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassificationReport.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassificationReport.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassificationReport.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,101 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api;
+
+import java.util.ArrayList;
+import java.util.Date;
+import java.util.List;
+
+/**
+ * Data transfer object to report estimated classification performance of a classifier.
+ * 
+ * <p>
+ * Report scores to evaluate the quality of a model on a labeled evaluation dataset (that should not have been
+ * used when training the model).
+ * </p>
+ * 
+ * <p>
+ * See: http://en.wikipedia.org/wiki/Precision_and_recall
+ * </p>
+ * 
+ * <p>
+ * Precision, Recall are F1-score and preferred over a simple rate of good classification so as to account for
+ * potentially imbalanced evaluation set (e.g. when the number of negative examples is much larger than the
+ * number of positive examples).
+ * </p>
+ */
+public class ClassificationReport {
+
+    /**
+     * Number of true positives divided by the sum of true positives and false positives.
+     */
+    public final float precision;
+
+    /**
+     * Number of true positives divided by the sum of true positives and false negatives.
+     */
+    public final float recall;
+
+    /**
+     * Harmonic mean of the precision and recall that balance the importance of false positive and false
+     * negatives equally.
+     */
+    public final float f1;
+
+    /**
+     * Total number of positive examples used by the evaluation procedure.
+     */
+    public final int positiveSupport;
+
+    /**
+     * Total number of negative examples used by the evaluation procedure.
+     */
+    public final int negativeSupport;
+
+    public final boolean uptodate;
+
+    public final Date evaluationDate;
+
+    public final List<String> falsePositiveExampleIds = new ArrayList<String>();
+
+    public final List<String> falseNegativeExampleIds = new ArrayList<String>();
+
+    public ClassificationReport(float precision,
+                                float recall,
+                                int positiveSupport,
+                                int negativeSupport,
+                                boolean uptodate,
+                                Date evaluationDate) {
+        this.precision = precision;
+        this.recall = recall;
+        if (precision != 0 || recall != 0) {
+            this.f1 = 2 * precision * recall / (precision + recall);
+        } else {
+            this.f1 = 0;
+        }
+        this.positiveSupport = positiveSupport;
+        this.negativeSupport = negativeSupport;
+        this.uptodate = uptodate;
+        this.evaluationDate = evaluationDate;
+    }
+
+    @Override
+    public String toString() {
+        return String.format("ClassificationReport: precision=%f, recall=%f, f1=%f", precision, recall, f1);
+    }
+
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassifierException.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassifierException.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassifierException.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/ClassifierException.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,39 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api;
+
+
+/**
+ * Exception raised when trying to classify a document or updating the classifier statistical model.
+ */
+public class ClassifierException extends Exception {
+
+    public ClassifierException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    public ClassifierException(String message) {
+        super(message);
+    }
+
+    public ClassifierException(Throwable cause) {
+        super(cause);
+    }
+
+    private static final long serialVersionUID = 1L;
+
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicClassifier.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicClassifier.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicClassifier.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicClassifier.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,184 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api;
+
+import org.apache.clerezza.rdf.core.Graph;
+import org.apache.clerezza.rdf.core.UriRef;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSet;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
+import org.osgi.framework.InvalidSyntaxException;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Service interface for suggesting hierarchical concepts from a specific scheme (a.k.a. taxonomy, thesaurus
+ * or concepts hierarchy) from the text content of a document or part of a document.
+ */
+public interface TopicClassifier {
+
+    /**
+     * The short name of the training set. Can be used as the URI component to identify the training set in
+     * the Web management interface or in RDF descriptions of the service.
+     */
+    String getName();
+
+    /**
+     * @return list of language codes for text that can be automatically classified by the service.
+     */
+    public List<String> getAcceptedLanguages();
+
+    /**
+     * Perform automated text categorization based on statistical occurrences of words in the given text.
+     * 
+     * @param text
+     *            the text content to analyze
+     * @return the most likely concepts related to the text
+     * @throws EngineException
+     */
+    List<TopicSuggestion> suggestTopics(String text) throws ClassifierException;
+
+    /**
+     * @return the set of ids of concepts directly broader than
+     * @param id
+     */
+    Set<String> getNarrowerConcepts(String broadConceptId) throws ClassifierException;
+
+    /**
+     * @return the set of ids of concepts directly narrower than
+     * @param id
+     */
+    Set<String> getBroaderConcepts(String id) throws ClassifierException;
+
+    /**
+     * @return the set of ids of concepts without broader concepts.
+     */
+    Set<String> getRootConcepts() throws ClassifierException;
+
+    /**
+     * @return true if the classifier model can be updated with the {@code addConcept} / {@code removeConcept}
+     *         / {@code updateModel} / methods.
+     */
+    boolean isUpdatable();
+
+    /**
+     * Register a topic and set it's ancestors in the taxonomy. Warning: re-adding an already existing topic
+     * can delete the underlying statistical model. Calling {@code updateModel} is necessary to rebuild the
+     * statistical model based on the hierarchical structure of the concepts and the registered training set.
+     * 
+     * @param conceptUri
+     *            the new concept identifier
+     * @param primaryTopicUri
+     *            optional identifier of a resource best describing that concept.
+     * @param broaderConcepts
+     *            list of directly broader concepts in the thesaurus
+     */
+    void addConcept(String conceptUri, String primaryTopicUri, Collection<String> broaderConcepts) throws ClassifierException;
+
+    /**
+     * Register a topic and set it's ancestors in the taxonomy. Warning: re-adding an already existing topic
+     * can delete the underlying statistical model. Calling {@code updateModel} is necessary to rebuild the
+     * statistical model based on the hierarchical structure of the concepts and the registered training set.
+     * 
+     * @param conceptUri
+     *            the new concept identifier
+     * @param broaderConcepts
+     *            list of directly broader concepts in the thesaurus
+     */
+    void addConcept(String conceptUri, Collection<String> broaderConcepts) throws ClassifierException;
+
+    /**
+     * Remove a topic from the thesaurus. WARNING: it is the caller responsibility to recursively remove or
+     * update any narrower topic that might hold a reference on this topic. Once the tree is updated,
+     * {@code updateModel} should be called to re-align the statistical model to match the new hierarchy by
+     * drawing examples from the dataset.
+     * 
+     * @param conceptUri
+     *            if of the topic to remove from the model, must not be null
+     */
+    void removeConcept(String conceptUri) throws ClassifierException;
+
+    /**
+     * Remove all the concepts from the current model leaving with an empty model.
+     * 
+     * @throws ClassifierException
+     */
+    void removeAllConcepts() throws ClassifierException;
+
+    /**
+     * @return the training set registered for this classifier (either set explicitly using setTrainingSet or
+     *         configured through OSGi properties).
+     */
+    public TrainingSet getTrainingSet();
+
+    /**
+     * Register a training set to use to build the statistical model of the classifier.
+     */
+    void setTrainingSet(TrainingSet trainingSet);
+
+    /**
+     * Update (incrementally or from scratch) the statistical model of the classifier. Note: depending on the
+     * size of the dataset and the number of concepts to update, this process can take a long time and should
+     * probably be wrapped in a dedicated thread if called by a the user interface layer.
+     * 
+     * @return the number of updated concepts
+     */
+    int updateModel(boolean incremental) throws TrainingSetException, ClassifierException;
+
+    /**
+     * Perform k-fold cross validation of the model to compute estimates of the precision, recall and f1
+     * score.
+     * 
+     * @return number of updated concepts
+     */
+    public int updatePerformanceEstimates(boolean incremental) throws ClassifierException,
+                                                              TrainingSetException;
+
+    /**
+     * Tell the classifier which slice of data to keep aside while training for model evaluation using k-folds
+     * cross validation.
+     * 
+     * http://en.wikipedia.org/wiki/Cross-validation_%28statistics%29#K-fold_cross-validation
+     * 
+     * @param foldIndex
+     *            the fold id used as a training set for this classifier instance.
+     * @param foldCount
+     *            the number of folds used in the cross validation process (typically 3 or 5). Set to 0 to
+     *            disable cross validation for this classifier.
+     */
+    void setCrossValidationInfo(int foldIndex, int foldCount);
+
+    /**
+     * Get a classification report with various accuracy metrics (precision, recall and f1-score) along with
+     * the example ids of some mistakes (false positives or false negatives).
+     */
+    ClassificationReport getPerformanceEstimates(String concept) throws ClassifierException;
+
+    /**
+     * Return the list of names of chains where the classifier is currently registered as an enhancement
+     * engine.
+     */
+    List<String> getChainNames() throws InvalidSyntaxException;
+
+    /**
+     * Initialize the concept hierarchy of the model using the provided RDF model (e.g. a SKOS taxonomy).
+     * 
+     * @return the number of concepts successfully imported (including roots).
+     */
+    int importConceptsFromGraph(Graph graph, UriRef conceptClass, UriRef broaderProperty) throws ClassifierException;
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicSuggestion.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicSuggestion.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicSuggestion.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/TopicSuggestion.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api;
+
+import org.apache.commons.lang.StringUtils;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * Data transfer object for the individual topic classification results.
+ */
+public class TopicSuggestion {
+
+    /**
+     * The URI of the concept in the hierarchical conceptual scheme (that holds the broader relationship)
+     */
+    public final String conceptUri;
+
+    /**
+     * Reference to the broader concepts of this suggestion.
+     */
+    public final List<String> broader = new ArrayList<String>();
+
+    /**
+     * The (optional) URI of a resource that grounds this concepts in the real world. Can be null.
+     */
+    public final String primaryTopicUri;
+
+    /**
+     * The (positive) score of the suggestion: higher is better. Zero would mean unrelated. The absolute value
+     * is meaningless: suggestions scores cannot be compared across different input text documents nor
+     * distinct concept schemes.
+     */
+    public final float score;
+
+    public TopicSuggestion(String conceptUri,
+                           String primaryTopicUri,
+                           Collection<? extends Object> broader,
+                           float score) {
+        this.conceptUri = conceptUri;
+        this.primaryTopicUri = primaryTopicUri;
+        if (broader != null) {
+            for (Object broaderConcept : broader) {
+                this.broader.add(broaderConcept.toString());
+            }
+        }
+        this.score = score;
+    }
+
+    public TopicSuggestion(String conceptUri, float score) {
+        this(conceptUri, null, null, score);
+    }
+
+    @Override
+    public String toString() {
+        return String.format("TopicSuggestion(\"%s\", [%s], %f)", conceptUri,
+            StringUtils.join(broader, "\", \""), score);
+    }
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/Example.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/Example.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/Example.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/Example.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,63 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api.training;
+
+import org.apache.commons.lang.StringUtils;
+
+import java.util.Collection;
+
+/**
+ * Data transfer object to pack the items of a multi-label text classification training set.
+ */
+public class Example {
+
+    /**
+     * Unique id of the document
+     */
+    public final String id;
+
+    /**
+     * Identifier of the labels (categories, topics, tags...) of the document. This is the target signal to
+     * predict.
+     * 
+     * In practice this is expected to be a collection of String items but we do not enforce the cast to avoid
+     * the GC overhead and be able to work with the native data-structures returned by SolrJ.
+     */
+    public final Collection<Object> labels;
+
+    /**
+     * Text fields of the document (could be headers, paragraphs, text extractions of PDF files...). Any
+     * markup is assumed to have been cleaned up in some preprocessing step.
+     * 
+     * In practice this is expected to be a collection of String items but we do not enforce the cast to avoid
+     * the GC overhead and be able to work with the native data-structures returned by SolrJ.
+     */
+    public final Collection<Object> contents;
+
+    public Example(String id, Collection<Object> labelValues, Collection<Object> textValues) {
+        this.id = id;
+        this.labels = labelValues;
+        this.contents = textValues;
+    }
+
+    /**
+     * @return concatenated version of the content fields.
+     */
+    public String getContentString() {
+        return StringUtils.join(contents, "\n\n");
+    }
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSet.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSet.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSet.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSet.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,111 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api.training;
+
+import org.apache.stanbol.enhancer.topic.api.Batch;
+
+import java.util.Date;
+import java.util.List;
+
+/**
+ * Source of categorized text documents that can be used to build a the statistical model of a
+ * TopicClassifier.
+ */
+public interface TrainingSet {
+
+    /**
+     * The short name of the training set. Can be used as the URI component to identify the training set in
+     * the Web management interface or in RDF descriptions of the service.
+     */
+    String getName();
+
+    /**
+     * @return true if the training set can be updated using the {@code registerExample} API. If false that
+     *         means that the component is a view on a remote datasource that has its own API for updates
+     *         (e.g. the document repository of a CMS).
+     */
+    boolean isUpdatable() throws TrainingSetException;
+
+    /**
+     * Register some text content to be used as an example of document that should be positively classified as
+     * topics by the model.
+     * 
+     * @param id
+     *            Unique identifier of the example to create or override. If null, a new example with a
+     *            generated id will be created.
+     * @param text
+     *            Text content of the example. If null the example with the matching id will be deleted.
+     * 
+     * @param topics
+     *            The list of all the topics the example should be classified as.
+     * @return the id of the registered example (can be automatically generated)
+     */
+    String registerExample(String exampleId, String text, List<String> topics) throws TrainingSetException;
+
+    /**
+     * Fetch examples representative of the set of topics passed as argument so as to be able to build a
+     * statistical model.
+     * 
+     * @param topics
+     *            list of admissible topics to search examples for: each example in the batch will be
+     *            classified in at list one of the requested topics. This list would typically comprise a
+     *            topic along with it's direct narrower descendants (and maybe level 2 descendants too).
+     * @param offset
+     *            marker value to fetch the next batch. Pass null to fetch the first batch.
+     * @return a batch of example suitable for training a classifier model for the requested topics.
+     */
+    Batch<Example> getPositiveExamples(List<String> topics, Object offset) throws TrainingSetException;
+
+    /**
+     * Fetch examples representative of any document not specifically classified in one of the passed topics.
+     * This can be useful to train a statistical model for a classifier of those topics to negatively weight
+     * generic features (term occurrences) and limit the number of false positives in the classification. It
+     * is up to the classifier model to decide to use such negative examples or not at training time.
+     * 
+     * @param topics
+     *            list of non-admissible topics to search example for: each example in the batch must no be
+     *            classified in any of the passed topics.
+     * @param offset
+     *            marker value to fetch the next batch. Pass null to fetch the first batch.
+     * @return a batch of examples suitable for training (negative-refinement) a classifier model for the
+     *         requested topics.
+     */
+    Batch<Example> getNegativeExamples(List<String> topics, Object offset) throws TrainingSetException;
+
+    /**
+     * Number of examples to fetch at once.
+     */
+    void setBatchSize(int batchSize);
+
+    /**
+     * Method to tell the classifier if topic model should be updated if there exists examples classified in
+     * one of those topics that has changed.
+     * 
+     * @param topics
+     *            topics to check
+     * @param referenceDate
+     *            look for changes after that date
+     * @return true if one of the passed topics has changed since the last date
+     */
+    boolean hasChangedSince(List<String> topics, Date referenceDate) throws TrainingSetException;
+
+    /**
+     * Trigger optimization of the underlying index. 
+     */
+    void optimize() throws TrainingSetException;
+
+}

Added: stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSetException.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSetException.java?rev=1518628&view=auto
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSetException.java (added)
+++ stanbol/trunk/enhancement-engines/topic/api/src/main/java/org/apache/stanbol/enhancer/topic/api/training/TrainingSetException.java Thu Aug 29 12:57:55 2013
@@ -0,0 +1,36 @@
+/*
+ * 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.
+ */
+package org.apache.stanbol.enhancer.topic.api.training;
+
+import java.io.IOException;
+
+/**
+ * Unexpected Error while performing read or write access to a topic classifier training set.
+ */
+public class TrainingSetException extends IOException {
+
+    private static final long serialVersionUID = 1L;
+
+    public TrainingSetException(String message) {
+        super(message);
+    }
+
+    public TrainingSetException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+}

Modified: stanbol/trunk/enhancement-engines/topic/engine/pom.xml
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/engine/pom.xml?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/engine/pom.xml (original)
+++ stanbol/trunk/enhancement-engines/topic/engine/pom.xml Thu Aug 29 12:57:55 2013
@@ -63,14 +63,10 @@
             <Import-Package>
               org.apache.stanbol.enhancer.servicesapi; provide:=true; version="[0.10,0.12)",
               org.apache.stanbol.enhancer.servicesapi.impl; provide:=true; version="[0.10,0.12)",
-              org.apache.stanbol.enhancer.topic,
-              org.apache.stanbol.enhancer.topic.training,
+              org.apache.stanbol.enhancer.topic.api.*,
               *
             </Import-Package>
-            <Export-Package>
-              org.apache.stanbol.enhancer.topic;version=${project.version},
-              org.apache.stanbol.enhancer.topic.training;version=${project.version}
-            </Export-Package>
+            <Export-Package></Export-Package>
             <Private-Package>
               org.apache.stanbol.enhancer.engine.topic
             </Private-Package>
@@ -303,7 +299,14 @@
       <groupId>org.apache.stanbol</groupId>
       <artifactId>org.apache.stanbol.commons.solr.managed</artifactId>
       <version>0.12.0-SNAPSHOT</version>
-    </dependency>    
+    </dependency>
+
+      <!-- API dependency -->
+      <dependency>
+          <groupId>org.apache.stanbol</groupId>
+          <artifactId>org.apache.stanbol.enhancer.engine.topic.api</artifactId>
+          <version>0.10.1-SNAPSHOT</version>
+      </dependency>
   </dependencies>
 
 </project>

Modified: stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/engine/topic/TopicClassificationEngine.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/engine/topic/TopicClassificationEngine.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/engine/topic/TopicClassificationEngine.java (original)
+++ stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/engine/topic/TopicClassificationEngine.java Thu Aug 29 12:57:55 2013
@@ -84,19 +84,19 @@ import org.apache.stanbol.enhancer.servi
 import org.apache.stanbol.enhancer.servicesapi.rdf.NamespaceEnum;
 import org.apache.stanbol.enhancer.servicesapi.rdf.OntologicalClasses;
 import org.apache.stanbol.enhancer.servicesapi.rdf.TechnicalClasses;
-import org.apache.stanbol.enhancer.topic.Batch;
-import org.apache.stanbol.enhancer.topic.BatchProcessor;
-import org.apache.stanbol.enhancer.topic.ClassificationReport;
-import org.apache.stanbol.enhancer.topic.ClassifierException;
 import org.apache.stanbol.enhancer.topic.ConfiguredSolrCoreTracker;
 import org.apache.stanbol.enhancer.topic.EmbeddedSolrHelper;
-import org.apache.stanbol.enhancer.topic.TopicClassifier;
-import org.apache.stanbol.enhancer.topic.TopicSuggestion;
 import org.apache.stanbol.enhancer.topic.UTCTimeStamper;
-import org.apache.stanbol.enhancer.topic.training.Example;
+import org.apache.stanbol.enhancer.topic.api.Batch;
+import org.apache.stanbol.enhancer.topic.api.BatchProcessor;
+import org.apache.stanbol.enhancer.topic.api.ClassificationReport;
+import org.apache.stanbol.enhancer.topic.api.ClassifierException;
+import org.apache.stanbol.enhancer.topic.api.TopicClassifier;
+import org.apache.stanbol.enhancer.topic.api.TopicSuggestion;
+import org.apache.stanbol.enhancer.topic.api.training.Example;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSet;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
 import org.apache.stanbol.enhancer.topic.training.SolrTrainingSet;
-import org.apache.stanbol.enhancer.topic.training.TrainingSet;
-import org.apache.stanbol.enhancer.topic.training.TrainingSetException;
 import org.apache.stanbol.entityhub.servicesapi.Entityhub;
 import org.apache.stanbol.entityhub.servicesapi.EntityhubException;
 import org.apache.stanbol.entityhub.servicesapi.model.Entity;
@@ -148,26 +148,27 @@ import org.slf4j.LoggerFactory;
         @Property(name = TopicClassificationEngine.SOLR_CORE_CONFIG,
             value = TopicClassificationEngine.DEFAULT_SOLR_CORE_CONFIG),
         @Property(name = TopicClassificationEngine.LANGUAGES),
-// those properties can still be set via a configuration file, but as most users
-// will not use them exclude those from the configuration form
-//        @Property(name = TopicClassificationEngine.SIMILARTITY_FIELD, value = TopicClassificationEngine.DEFAULT_SIMILARTITY_FIELD),
-//        @Property(name = TopicClassificationEngine.CONCEPT_URI_FIELD, value = TopicClassificationEngine.DEFAULT_CONCEPT_URI_FIELD),
-//        @Property(name = TopicClassificationEngine.PRIMARY_TOPIC_URI_FIELD, value = TopicClassificationEngine.DEFAULT_PRIMARY_TOPIC_URI_FIELD),
-//        @Property(name = TopicClassificationEngine.BROADER_FIELD, value = TopicClassificationEngine.DEFAULT_BROADER_FIELD),
-//        @Property(name = TopicClassificationEngine.MODEL_UPDATE_DATE_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_UPDATE_DATE_FIELD),
-//        @Property(name = TopicClassificationEngine.PRECISION_FIELD, value = TopicClassificationEngine.DEFAULT_PRECISION_FIELD),
-//        @Property(name = TopicClassificationEngine.RECALL_FIELD, value = TopicClassificationEngine.DEFAULT_RECALL_FIELD),
-//        @Property(name = TopicClassificationEngine.ENTRY_ID_FIELD, value = TopicClassificationEngine.DEFAULT_ENTRY_ID_FIELD),
-//        @Property(name = TopicClassificationEngine.MODEL_ENTRY_ID_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_ENTRY_ID_FIELD),
-//        @Property(name = TopicClassificationEngine.ENTRY_TYPE_FIELD, value = TopicClassificationEngine.DEFAULT_ENTRY_TYPE_FIELD),
-//        @Property(name = TopicClassificationEngine.MODEL_EVALUATION_DATE_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_EVALUATION_DATE_FIELD),
-//        @Property(name = TopicClassificationEngine.FALSE_NEGATIVES_FIELD, value = TopicClassificationEngine.DEFAULT_FALSE_NEGATIVES_FIELD),
-//        @Property(name = TopicClassificationEngine.FALSE_POSITIVES_FIELD, value = TopicClassificationEngine.DEFAULT_FALSE_POSITIVES_FIELD),
-//        @Property(name = TopicClassificationEngine.POSITIVE_SUPPORT_FIELD, value = TopicClassificationEngine.DEFAULT_POSITIVE_SUPPORT_FIELD),
-//        @Property(name = TopicClassificationEngine.NEGATIVE_SUPPORT_FIELD, value = TopicClassificationEngine.DEFAULT_NEGATIVE_SUPPORT_FIELD),
-//        @Property(name = TopicClassificationEngine.ORDER, intValue = TopicClassificationEngine.DEFAULT_ENGINE_ORDER),
+     // those properties can still be set via a configuration file, but as most users
+     // will not use them exclude those from the configuration form
+//             @Property(name = TopicClassificationEngine.SIMILARTITY_FIELD, value = TopicClassificationEngine.DEFAULT_SIMILARTITY_FIELD),
+//             @Property(name = TopicClassificationEngine.CONCEPT_URI_FIELD, value = TopicClassificationEngine.DEFAULT_CONCEPT_URI_FIELD),
+//             @Property(name = TopicClassificationEngine.PRIMARY_TOPIC_URI_FIELD, value = TopicClassificationEngine.DEFAULT_PRIMARY_TOPIC_URI_FIELD),
+//             @Property(name = TopicClassificationEngine.BROADER_FIELD, value = TopicClassificationEngine.DEFAULT_BROADER_FIELD),
+//             @Property(name = TopicClassificationEngine.MODEL_UPDATE_DATE_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_UPDATE_DATE_FIELD),
+//             @Property(name = TopicClassificationEngine.PRECISION_FIELD, value = TopicClassificationEngine.DEFAULT_PRECISION_FIELD),
+//             @Property(name = TopicClassificationEngine.RECALL_FIELD, value = TopicClassificationEngine.DEFAULT_RECALL_FIELD),
+//             @Property(name = TopicClassificationEngine.ENTRY_ID_FIELD, value = TopicClassificationEngine.DEFAULT_ENTRY_ID_FIELD),
+//             @Property(name = TopicClassificationEngine.MODEL_ENTRY_ID_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_ENTRY_ID_FIELD),
+//             @Property(name = TopicClassificationEngine.ENTRY_TYPE_FIELD, value = TopicClassificationEngine.DEFAULT_ENTRY_TYPE_FIELD),
+//             @Property(name = TopicClassificationEngine.MODEL_EVALUATION_DATE_FIELD, value = TopicClassificationEngine.DEFAULT_MODEL_EVALUATION_DATE_FIELD),
+//             @Property(name = TopicClassificationEngine.FALSE_NEGATIVES_FIELD, value = TopicClassificationEngine.DEFAULT_FALSE_NEGATIVES_FIELD),
+//             @Property(name = TopicClassificationEngine.FALSE_POSITIVES_FIELD, value = TopicClassificationEngine.DEFAULT_FALSE_POSITIVES_FIELD),
+//             @Property(name = TopicClassificationEngine.POSITIVE_SUPPORT_FIELD, value = TopicClassificationEngine.DEFAULT_POSITIVE_SUPPORT_FIELD),
+//             @Property(name = TopicClassificationEngine.NEGATIVE_SUPPORT_FIELD, value = TopicClassificationEngine.DEFAULT_NEGATIVE_SUPPORT_FIELD),
+//             @Property(name = TopicClassificationEngine.ORDER, intValue = TopicClassificationEngine.DEFAULT_ENGINE_ORDER),
         @Property(name = TopicClassificationEngine.TRAINING_SET_ID),
-        @Property(name = Constants.SERVICE_RANKING, intValue = 0)})
+        @Property(name = Constants.SERVICE_RANKING, intValue = 0)
+})
 public class TopicClassificationEngine extends ConfiguredSolrCoreTracker implements EnhancementEngine,
         ServiceProperties, TopicClassifier {
 
@@ -1488,15 +1489,19 @@ public class TopicClassificationEngine e
     }
 
     @Override
-    public List<String> getChainNames() throws InvalidSyntaxException, ChainException {
+    public List<String> getChainNames() throws InvalidSyntaxException {
         List<String> chainNames = new ArrayList<String>();
         BundleContext bundleContext = context.getBundleContext();
         ServiceReference[] references = bundleContext.getServiceReferences(Chain.class.getName(), null);
         if (references != null) {
             for (ServiceReference ref : references) {
                 Chain chain = (Chain) bundleContext.getService(ref);
-                if (chain.getEngines().contains(getName())) {
-                    chainNames.add(chain.getName());
+                try {
+                    if (chain.getEngines().contains(getName())) {
+                        chainNames.add(chain.getName());
+                    }
+                } catch (ChainException e) {
+                    // This chain is currently not active ... ignore
                 }
             }
         }

Modified: stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/SolrTrainingSet.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/SolrTrainingSet.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/SolrTrainingSet.java (original)
+++ stanbol/trunk/enhancement-engines/topic/engine/src/main/java/org/apache/stanbol/enhancer/topic/training/SolrTrainingSet.java Thu Aug 29 12:57:55 2013
@@ -43,10 +43,12 @@ import org.apache.solr.client.solrj.util
 import org.apache.solr.common.SolrDocument;
 import org.apache.solr.common.SolrInputDocument;
 import org.apache.stanbol.commons.solr.managed.ManagedSolrServer;
-import org.apache.stanbol.commons.stanboltools.datafileprovider.DataFileProvider;
-import org.apache.stanbol.enhancer.topic.Batch;
 import org.apache.stanbol.enhancer.topic.ConfiguredSolrCoreTracker;
 import org.apache.stanbol.enhancer.topic.UTCTimeStamper;
+import org.apache.stanbol.enhancer.topic.api.Batch;
+import org.apache.stanbol.enhancer.topic.api.training.Example;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSet;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
 import org.osgi.framework.InvalidSyntaxException;
 import org.osgi.service.cm.ConfigurationException;
 import org.osgi.service.component.ComponentContext;

Modified: stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TopicEngineTest.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TopicEngineTest.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TopicEngineTest.java (original)
+++ stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TopicEngineTest.java Thu Aug 29 12:57:55 2013
@@ -51,12 +51,12 @@ import org.apache.stanbol.commons.solr.u
 import org.apache.stanbol.enhancer.servicesapi.EnhancementEngine;
 import org.apache.stanbol.enhancer.servicesapi.rdf.OntologicalClasses;
 import org.apache.stanbol.enhancer.servicesapi.rdf.Properties;
-import org.apache.stanbol.enhancer.topic.ClassificationReport;
-import org.apache.stanbol.enhancer.topic.ClassifierException;
 import org.apache.stanbol.enhancer.topic.EmbeddedSolrHelper;
-import org.apache.stanbol.enhancer.topic.TopicSuggestion;
+import org.apache.stanbol.enhancer.topic.api.ClassificationReport;
+import org.apache.stanbol.enhancer.topic.api.ClassifierException;
+import org.apache.stanbol.enhancer.topic.api.TopicSuggestion;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
 import org.apache.stanbol.enhancer.topic.training.SolrTrainingSet;
-import org.apache.stanbol.enhancer.topic.training.TrainingSetException;
 import org.junit.After;
 import org.junit.AfterClass;
 import org.junit.Before;

Modified: stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TrainingSetTest.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TrainingSetTest.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TrainingSetTest.java (original)
+++ stanbol/trunk/enhancement-engines/topic/engine/src/test/java/org/apache/stanbol/enhancer/engine/topic/TrainingSetTest.java Thu Aug 29 12:57:55 2013
@@ -37,12 +37,12 @@ import javax.xml.parsers.ParserConfigura
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.FilenameUtils;
 import org.apache.solr.client.solrj.embedded.EmbeddedSolrServer;
-import org.apache.stanbol.enhancer.topic.Batch;
 import org.apache.stanbol.enhancer.topic.EmbeddedSolrHelper;
 import org.apache.stanbol.enhancer.topic.UTCTimeStamper;
-import org.apache.stanbol.enhancer.topic.training.Example;
+import org.apache.stanbol.enhancer.topic.api.Batch;
+import org.apache.stanbol.enhancer.topic.api.training.Example;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
 import org.apache.stanbol.enhancer.topic.training.SolrTrainingSet;
-import org.apache.stanbol.enhancer.topic.training.TrainingSetException;
 import org.junit.After;
 import org.junit.AfterClass;
 import org.junit.Before;

Modified: stanbol/trunk/enhancement-engines/topic/web/pom.xml
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/web/pom.xml?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/web/pom.xml (original)
+++ stanbol/trunk/enhancement-engines/topic/web/pom.xml Thu Aug 29 12:57:55 2013
@@ -110,6 +110,11 @@
       <artifactId>org.apache.stanbol.enhancer.servicesapi</artifactId>
       <version>0.10.0</version>
     </dependency>
+      <dependency>
+          <groupId>org.apache.stanbol</groupId>
+          <artifactId>org.apache.stanbol.enhancer.engine.topic.api</artifactId>
+          <version>0.10.1-SNAPSHOT</version>
+      </dependency>
     <dependency>
       <groupId>org.apache.stanbol</groupId>
       <artifactId>org.apache.stanbol.enhancer.engine.topic</artifactId>

Modified: stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicClassifierRootResource.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicClassifierRootResource.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicClassifierRootResource.java (original)
+++ stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicClassifierRootResource.java Thu Aug 29 12:57:55 2013
@@ -16,12 +16,15 @@
  */
 package org.apache.stanbol.enhancer.web.topic.resource;
 
-import static javax.ws.rs.core.MediaType.TEXT_HTML;
-import static org.apache.stanbol.commons.web.base.CorsHelper.addCORSOrigin;
-import static org.apache.stanbol.commons.web.base.CorsHelper.enableCORS;
-
-import java.util.ArrayList;
-import java.util.List;
+import org.apache.stanbol.commons.viewable.Viewable;
+import org.apache.stanbol.commons.web.base.ContextHelper;
+import org.apache.stanbol.commons.web.base.resource.BaseStanbolResource;
+import org.apache.stanbol.enhancer.topic.api.TopicClassifier;
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.InvalidSyntaxException;
+import org.osgi.framework.ServiceReference;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import javax.ws.rs.GET;
 import javax.ws.rs.OPTIONS;
@@ -31,16 +34,12 @@ import javax.ws.rs.core.Context;
 import javax.ws.rs.core.HttpHeaders;
 import javax.ws.rs.core.Response;
 import javax.ws.rs.core.Response.ResponseBuilder;
+import java.util.ArrayList;
+import java.util.List;
 
-import org.apache.stanbol.commons.viewable.Viewable;
-import org.apache.stanbol.commons.web.base.ContextHelper;
-import org.apache.stanbol.commons.web.base.resource.BaseStanbolResource;
-import org.apache.stanbol.enhancer.topic.TopicClassifier;
-import org.osgi.framework.BundleContext;
-import org.osgi.framework.InvalidSyntaxException;
-import org.osgi.framework.ServiceReference;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
+import static javax.ws.rs.core.MediaType.TEXT_HTML;
+import static org.apache.stanbol.commons.web.base.CorsHelper.addCORSOrigin;
+import static org.apache.stanbol.commons.web.base.CorsHelper.enableCORS;
 
 
 @Path("/topic")

Modified: stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicModelResource.java
URL: http://svn.apache.org/viewvc/stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicModelResource.java?rev=1518628&r1=1518627&r2=1518628&view=diff
==============================================================================
--- stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicModelResource.java (original)
+++ stanbol/trunk/enhancement-engines/topic/web/src/main/java/org/apache/stanbol/enhancer/web/topic/resource/TopicModelResource.java Thu Aug 29 12:57:55 2013
@@ -16,30 +16,6 @@
  */
 package org.apache.stanbol.enhancer.web.topic.resource;
 
-import static javax.ws.rs.core.MediaType.TEXT_HTML;
-import static org.apache.stanbol.commons.web.base.CorsHelper.addCORSOrigin;
-import static org.apache.stanbol.commons.web.base.CorsHelper.enableCORS;
-
-import java.util.List;
-
-import javax.servlet.ServletContext;
-import javax.ws.rs.Consumes;
-import javax.ws.rs.DELETE;
-import javax.ws.rs.GET;
-import javax.ws.rs.OPTIONS;
-import javax.ws.rs.POST;
-import javax.ws.rs.Path;
-import javax.ws.rs.PathParam;
-import javax.ws.rs.Produces;
-import javax.ws.rs.QueryParam;
-import javax.ws.rs.WebApplicationException;
-import javax.ws.rs.core.Context;
-import javax.ws.rs.core.HttpHeaders;
-import javax.ws.rs.core.MediaType;
-import javax.ws.rs.core.Response;
-import javax.ws.rs.core.Response.ResponseBuilder;
-import javax.ws.rs.core.UriInfo;
-
 import org.apache.clerezza.rdf.core.Graph;
 import org.apache.clerezza.rdf.core.UriRef;
 import org.apache.stanbol.commons.viewable.Viewable;
@@ -48,14 +24,24 @@ import org.apache.stanbol.commons.web.ba
 import org.apache.stanbol.enhancer.servicesapi.EnhancementEngine;
 import org.apache.stanbol.enhancer.servicesapi.rdf.OntologicalClasses;
 import org.apache.stanbol.enhancer.servicesapi.rdf.Properties;
-import org.apache.stanbol.enhancer.topic.ClassifierException;
-import org.apache.stanbol.enhancer.topic.TopicClassifier;
-import org.apache.stanbol.enhancer.topic.training.TrainingSet;
-import org.apache.stanbol.enhancer.topic.training.TrainingSetException;
+import org.apache.stanbol.enhancer.topic.api.ClassifierException;
+import org.apache.stanbol.enhancer.topic.api.TopicClassifier;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSet;
+import org.apache.stanbol.enhancer.topic.api.training.TrainingSetException;
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.InvalidSyntaxException;
 import org.osgi.framework.ServiceReference;
 
+import javax.servlet.ServletContext;
+import javax.ws.rs.*;
+import javax.ws.rs.core.*;
+import javax.ws.rs.core.Response.ResponseBuilder;
+import java.util.List;
+
+import static javax.ws.rs.core.MediaType.TEXT_HTML;
+import static org.apache.stanbol.commons.web.base.CorsHelper.addCORSOrigin;
+import static org.apache.stanbol.commons.web.base.CorsHelper.enableCORS;
+
 
 /**
  * RESTful interface for classification models: register concept hierarchies, introspect model state and