Added errorcodes
diff --git a/Changes b/Changes
index ede43f5..646b434 100644
--- a/Changes
+++ b/Changes
@@ -18,7 +18,8 @@
renamed KorapResponse to Response,
moved model/* to index,
moved meta/SearchContext to response/SearchContext,
- krillified property files (diewald)
+ krillified property files,
+ added Errorcodes (diewald)
- [documentation] Improved documentation for API classes (diewald)
0.50 2015-02-23
diff --git a/Errorcodes b/Errorcodes
new file mode 100644
index 0000000..537da15
--- /dev/null
+++ b/Errorcodes
@@ -0,0 +1,78 @@
+* 600 - 699 - Lucene Backend error codes
+600: "Unable to read index"
+601: "Unable to find index"
+602: "Unable to add document to index"
+603: "Unable to commit staged data to index"
+604: "Unable to connect to database"
+610: "Missing request parameters"
+620: "Unable to generate JSON"
+621: "Unable to parse JSON"
+680: "Server is up and running!"
+681: "Document was added successfully", document id
+682: "Response time exceeded"
+
+* 700 - 799 - Coral Deserialization errors
+700: "No Query given"
+701: "JSON-LD group has no @type attribute"
+702: "Boundary definition is invalid"
+703: "Group expects operation"
+704: "Operation needs operand list"
+705: "Number of operands is not acceptable"
+706: "Frame type is unknown"
+707: "Distance Constraints have to be defined as arrays"
+708: "No valid distances defined"
+709: "Valid class numbers exceeded"
+710: "Class attribute missing"
+711: "Unknown group operation"
+712: "Unknown reference operation"
+713: "Query type is not supported"
+714: "Span references expect a start position and a length parameter"
+715: "Attribute type is not supported"
+716: "Unknown relation"
+740: "Key definition is missing in term or span"
+741: "Match relation unknown"
+742: "Term group needs operand list"
+743: "Term group expects a relation"
+744: "Operand not supported in term group"
+745: "Token type is not supported"
+746: "Term type is not supported - treated as a string"
+747: "Attribute is null"
+750: "Passed notifications are not well formed"
+760: "Exclusion is currently not supported in position operations"
+761: "Class reference operators are currently not supported"
+762: "Span references are currently not supported" (Not in use)
+763: "Excluding distance constraints are currently not supported"
+764: "Class reference checks are currently not supported - results may not be correct"
+765: "Relations are currently not supported"
+766: "Peripheral references are currently not supported"
+767: "Case insensitivity is currently not supported for this layer"
+768: "Attributes are currently not supported - results may not be correct"
+769: "Overlap variant currently interpreted as overlap"
+770: "Arity attributes are currently not supported - results may not be correct"
+771: "Arbitrary elements with attributes are currently not supported"
+780: "This query matches everywhere"
+781: "Optionality of query is ignored"
+782: "Exclusivity of query is ignored"
+799: Unknown query serialization message (Arbitrary string)
+
+* 800 - 899 - Virtual Collection Messages
+802: "Match type is not supported by value type"
+804: "Unknown value type"
+805: "Value is invalid"
+806: "Value is not a valid date string"
+807: "Value is not a valid regular expression"
+810: "Unknown document group operation" (like 711)
+811: "Document group expects operation" (like 703)
+812: "Operand not supported in document group" (like 744)
+813: "Collection type is not supported" (like 713)
+814: "Unknown rewrite operation"
+815: "Rewrite expects source"
+830: "Filter was empty"
+831: "Filter is not wrappable"
+832: "Filter operation is invalid"
+850: "Collections are deprecated in favour of a single collection"
+851: "Legacy filters need @value fields"
+
+* 900 - 999 - Corpus Data errors
+952: "Given offset information is not numeric"
+953: "Given offset information is incomplete"
\ No newline at end of file
diff --git a/src/main/java/de/ids_mannheim/korap/Krill.java b/src/main/java/de/ids_mannheim/korap/Krill.java
index 6fb9fb1..0fdf5d0 100644
--- a/src/main/java/de/ids_mannheim/korap/Krill.java
+++ b/src/main/java/de/ids_mannheim/korap/Krill.java
@@ -18,17 +18,30 @@
import org.slf4j.LoggerFactory;
/**
- * Krill is a corpus data retrieval index using Lucene for Look-Ups.
+ * <p>Krill is a corpus data retrieval index using Lucene for Look-Ups.</p>
+ *
+ * <p>
* It is the reference implementation for KoralQuery consumption,
- * and supports specified query and collection objects,
- * and proprietary meta objects.
+ * and this class acts as the central point for consuming and
+ * responding to KoralQuery requests.
+ * </p>
+ *
+ * <p>
+ * The processing of the collection section of the request is delegated
+ * to {@link KrillCollection}, the query section to {@link KrillQuery},
+ * and the meta section to {@link KrillMeta}.
+ * </p>
*
* <blockquote><pre>
- * // Create a new krill search object by passing a KoralQuery string
- * Krill krill = new Krill(koralQueryString);
+ * // Create or receive a KoralQuery JSON string
+ * String koral = "{\"query\":{...}, \"collection\":{...}, ... }";
+ *
+ * // Create a new krill search object by passing the Query
+ * Krill krill = new Krill(koral);
*
* // Apply the query to an index and receive a search result
- * Result result = krill.apply(new KrillIndex());
+ * // This may invoke different actions depending on the request
+ * Result result = krill.setIndex(new KrillIndex()).apply();
* </pre></blockquote>
*
* @author diewald
@@ -39,9 +52,7 @@
* @see KrillMeta
* @see KrillIndex
*/
-/*
- * Todo: Use a configuration file
- */
+// Todo: Use a krill.properties configuration file
public class Krill extends Response {
private KrillIndex index;
private SpanQuery spanQuery;
@@ -153,6 +164,7 @@
this.addError(780, "This query matches everywhere");
else {
+
// Serialize a Lucene SpanQuery based on the SpanQueryWrapper
this.spanQuery = qw.toQuery();
@@ -182,7 +194,7 @@
// Copy notifications from request
this.copyNotificationsFrom(json);
- // Parse virtual collections
+ // Parse "collection" or "collections" attribute
try {
if (json.has("collection")) {
this.setCollection(
@@ -205,7 +217,7 @@
this.addError(q.getErrorCode(), q.getMessage());
};
- // Parse meta object
+ // Parse "meta" attribute
if (!this.hasErrors() && json.has("meta"))
this.setMeta(new KrillMeta(json.get("meta")));
@@ -224,7 +236,7 @@
/**
- * Set the associated {@link KrillIndex} object.
+ * Set the {@link KrillIndex} object.
*
* @param index The associated {@link KrillIndex} object.
* @return The {@link Krill} object for chaining.
@@ -237,6 +249,9 @@
/**
* Apply the KoralQuery to an index.
+ * This may invoke different actions depending
+ * on the meta information, like {@link KrillIndex#search}
+ * or {@link KrillIndex#collect}.
*
* @param index The {@link KrillIndex}
* the search should be applyied to.
@@ -249,6 +264,9 @@
/**
* Apply the KoralQuery to an index.
+ * This may invoke different actions depending
+ * on the meta information, like {@link KrillIndex#search}
+ * or {@link KrillIndex#collect}.
*
* @return The result as a {@link Result} object.
*/
diff --git a/src/main/java/de/ids_mannheim/korap/KrillQuery.java b/src/main/java/de/ids_mannheim/korap/KrillQuery.java
index d7b68dc..7ad031e 100644
--- a/src/main/java/de/ids_mannheim/korap/KrillQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/KrillQuery.java
@@ -19,10 +19,15 @@
import de.ids_mannheim.korap.util.QueryException;
/**
+ * <p>
* KrillQuery provides deserialization methods
* for KoralQuery query objects.
+ * </p>
*
* <blockquote><pre>
+ * // Create or receive a KoralQuery JSON string
+ * String koral = "{\"@type\":"koral:group", ... }";
+ *
* SpanQueryWrapper sqw = new KrillQuery("tokens").fromJson("{... JsonString ...}");
* </pre></blockquote>
*
@@ -37,7 +42,7 @@
e.g. der alte []
should be wrapped in a contains(<base/s=t>) to ensure
they are not outside the text.
-
+
TODO: Create Pre-filter while preparing a Query.
The pre-filter will contain a boolena query with all
necessary terms, supporting boolean OR, ignoring
@@ -46,8 +51,8 @@
Search for all documents containing "s:Der" and ("s:alte" or "s:junge") and "s:Mann"
*/
public class KrillQuery extends Notifications {
- private String field;
private QueryBuilder builder;
+ private String field;
private JsonNode json;
// Logger
@@ -69,19 +74,6 @@
private static final int MAX_CLASS_NUM = 255; // 127;
- /**
- * Constructs a new object for query deserialization
- * and building. Expects the name of an index field
- * to apply the query on (this should normally be
- * a token stream field).
- *
- * @param field The specific index field for the query.
- */
- public KrillQuery (String field) {
- this.field = field;
- };
-
-
// Private class for koral:boundary objects
private class Boundary {
public int min, max;
@@ -117,17 +109,33 @@
};
};
+ /**
+ * Constructs a new object for query deserialization
+ * and building. Expects the name of an index field
+ * to apply the query on (this should normally be
+ * a token stream field).
+ *
+ * @param field The specific index field for the query.
+ */
+ public KrillQuery (String field) {
+ this.field = field;
+ };
+
/**
- * Deserialize JSON-LD query to a {@link SpanQueryWrapper} object.
+ * <p>Deserialize JSON-LD query to a {@link SpanQueryWrapper} object.</p>
*
- * <p>
* <blockquote><pre>
* KrillQuery kq = new KrillQuery("tokens");
- * SpanQueryWrapper sqw = kq.fromJson('{"@type":"koral:token","wrap":{' +
- * '"@type":"koral:term","foundry":"opennlp",' +
- * '"key":"tree","layer":"orth",' +
- * '"match":"match:eq"}}'
+ * SpanQueryWrapper sqw = kq.fromJson(
+ * "{\"@type\" : \"koral:token\","+
+ * "\"wrap\" : {" +
+ * "\"@type\" : \"koral:term\"," +
+ * "\"foundry\" : \"opennlp\"," +
+ * "\"key\" : \"tree\"," +
+ * "\"layer\" : \"orth\"," +
+ * "\"match\" : \"match:eq\""+
+ * "}}"
* );
* </pre></blockquote>
*
@@ -159,18 +167,22 @@
/**
- * Deserialize JSON-LD query as a {@link JsonNode} object
- * to a {@link SpanQueryWrapper} object.
+ * <p>Deserialize JSON-LD query as a {@link JsonNode} object
+ * to a {@link SpanQueryWrapper} object.</p>
*
* @param json {@link JsonNode} representing the JSON query string.
* @return {@link SpanQueryWrapper} object.
* @throws QueryException
*/
// TODO: Exception messages are horrible!
- // TODO: Use the shortcuts implemented in this class instead of the wrapper constructors
+ // TODO: Use the shortcuts implemented in the builder
+ // instead of the wrapper constructors
// TODO: Rename this span context!
public SpanQueryWrapper fromJson (JsonNode json) throws QueryException {
int number = 0;
+
+ // Only accept @typed objects for the moment
+ // TODO: Support @context for cosmas:...
if (!json.has("@type"))
throw new QueryException(701, "JSON-LD group has no @type attribute");
@@ -276,8 +288,16 @@
/**
+ * <p>
* Get the associated {@link QueryBuilder} object
* for query building.
+ * </p>
+ *
+ * <blockquote><pre>
+ * SpanQueryWrapper query = new KrillQuery("tokens").builder().re("mate/p=N.*");
+ * </pre></blockquote>
+ *
+ * @return The {@link QueryBuilder}.
*/
public QueryBuilder builder () {
if (this.builder == null)