Added comments.
Change-Id: I43518c832661499fa28426235efc96da091929bb
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanClassFilterQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanClassFilterQuery.java
index b5a8653..cc32ad6 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanClassFilterQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanClassFilterQuery.java
@@ -12,6 +12,11 @@
import de.ids_mannheim.korap.query.spans.ClassFilteredSpans;
+/** Filters query results by means of class operations.
+ *
+ * @author margaretha
+ *
+ */
public class SpanClassFilterQuery extends SimpleSpanQuery {
public enum ClassOperation {
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanReferenceQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanReferenceQuery.java
index 241b6ce..c50bc78 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanReferenceQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanReferenceQuery.java
@@ -12,11 +12,40 @@
import de.ids_mannheim.korap.query.spans.ReferenceSpans;
+/**
+ * SpanReferenceQuery ensures that a span involving in more than one
+ * operations are indeed the same spans. Such a span is referred by a
+ * class and cannot be ensured in one nested SpanQuery.
+ *
+ * For instance in the following Annis query
+ *
+ * <pre>
+ * cat="vb" & cat="prp" & cat="nn" & #1 .{0,1} #2 & #1 .{0,2} #3
+ * & #3 -> #2
+ * </pre>
+ *
+ * cat="prp" is referred by a class with number 2 and involves in two
+ * operations. After resolving the first and second operations, class
+ * number 3 and 2 have to be referred at the same time to solve the
+ * third operation. However, only one class can be focused on from a
+ * span at one time. Let say, class number 3 is focused on from the
+ * resulting spans of the first and second operation, then it is
+ * matched with a new span enumeration of cat="prp" for the third
+ * operation.
+ *
+ * SpanReferenceQuery ensures that cat="prp" spans in the third
+ * operation are the same as the those in the first operation by
+ * matching their positions using the class number 2 payloads kept in
+ * spans focussing on the class number 3 (it keeps all the payloads
+ * from previous operations).
+ *
+ * @author margaretha
+ *
+ */
public class SpanReferenceQuery extends SimpleSpanQuery {
private byte classNum;
-
public SpanReferenceQuery (SpanQuery firstClause, byte classNum,
boolean collectPayloads) {
super(firstClause, collectPayloads);
@@ -26,7 +55,6 @@
@Override
public SimpleSpanQuery clone () {
- // TODO Auto-generated method stub
return null;
}
@@ -34,7 +62,6 @@
@Override
public Spans getSpans (LeafReaderContext context, Bits acceptDocs,
Map<Term, TermContext> termContexts) throws IOException {
- // TODO Auto-generated method stub
return new ReferenceSpans(this, context, acceptDocs, termContexts);
}
@@ -51,11 +78,18 @@
}
+ /** Get the class number of the referred spans.
+ * @return the class number of the referred spans
+ */
public byte getClassNum () {
return classNum;
}
+ /** Set the class number of the referred spans.
+ *
+ * @param classNum the class number of the referred spans
+ */
public void setClassNum (byte classNum) {
this.classNum = classNum;
}
diff --git a/src/main/java/de/ids_mannheim/korap/query/SpanRelationMatchQuery.java b/src/main/java/de/ids_mannheim/korap/query/SpanRelationMatchQuery.java
index 311a5fc..de77ef4 100644
--- a/src/main/java/de/ids_mannheim/korap/query/SpanRelationMatchQuery.java
+++ b/src/main/java/de/ids_mannheim/korap/query/SpanRelationMatchQuery.java
@@ -12,6 +12,13 @@
import de.ids_mannheim.korap.query.spans.FocusSpans;
+/**
+ * Matches the source and/or target of a SpanRelationQuery to specific
+ * SpanQueries.
+ *
+ * @author margaretha
+ *
+ */
public class SpanRelationMatchQuery extends SimpleSpanQuery {
private SpanQuery operandQuery;
@@ -19,10 +26,25 @@
private SpanRelationQuery relationQuery;
+ /**
+ * Matches the left node of the given relation with the given
+ * SpanQuery.
+ *
+ * @param relation
+ * a SpanRelationQuery
+ * @param spanQuery
+ * a SpanQuery
+ * @param collectPayloads
+ * a boolean flag representing the value
+ * <code>true</code> if payloads are to be collected,
+ * otherwise
+ * <code>false</code>.
+ */
public SpanRelationMatchQuery (SpanRelationQuery relation,
- SpanQuery operand, boolean collectPayloads) {
+ SpanQuery spanQuery,
+ boolean collectPayloads) {
- checkVariables(relation, operand);
+ checkArguments(relation, spanQuery);
SpanFocusQuery sq = new SpanFocusQuery(
new SpanSegmentQuery(relationQuery, operandQuery, true),
relation.getTempClassNumbers());
@@ -36,10 +58,26 @@
}
+ /**
+ * Matches both the source and target of the given relations with
+ * the given operands.
+ *
+ * @param relation
+ * a SpanRelationQuery
+ * @param source
+ * a SpanQuery
+ * @param target
+ * a SpanQuery
+ * @param collectPayloads
+ * a boolean flag representing the value
+ * <code>true</code> if payloads are to be collected,
+ * otherwise
+ * <code>false</code>.
+ */
public SpanRelationMatchQuery (SpanRelationQuery relation, SpanQuery source,
SpanQuery target, boolean collectPayloads) {
- checkVariables(relation, source, target);
+ checkArguments(relation, source, target);
SpanFocusQuery sq = null;
SpanFocusQuery sq2 = null;
// match source and then target
@@ -76,30 +114,53 @@
}
- public void checkVariables (SpanRelationQuery relation, SpanQuery operand) {
+ /**
+ * Checks if the SpanRelationQuery and the SpanQuery are not null
+ * and if the SpanQuery has the same field as the
+ * SpanRelationQuery.
+ *
+ * @param relation
+ * SpanRelationQery
+ * @param spanQuery
+ * SpanQuery
+ */
+ public void checkArguments (SpanRelationQuery relation,
+ SpanQuery spanQuery) {
if (relation == null) {
throw new IllegalArgumentException(
"The relation query cannot be null.");
}
- if (operand == null) {
+ if (spanQuery == null) {
throw new IllegalArgumentException(
"The operand query cannot be null.");
}
this.field = relation.getField();
- if (!operand.getField().equals(field)) {
+ if (!spanQuery.getField().equals(field)) {
throw new IllegalArgumentException(
"Clauses must have the same field.");
}
this.relationQuery = relation;
- this.operandQuery = operand;
+ this.operandQuery = spanQuery;
}
- public void checkVariables (SpanRelationQuery relation, SpanQuery operand,
+ /**
+ * Checks if the SpanRelationQuery and the source and target
+ * SpanQuery are not null and if the SpanQueries have the same
+ * field as the SpanRelationQuery.
+ *
+ * @param relation
+ * SpanRelationQery
+ * @param source
+ * SpanQuery
+ * @param target
+ * SpanQuery
+ */
+ public void checkArguments (SpanRelationQuery relation, SpanQuery source,
SpanQuery target) {
- checkVariables(relation, operand);
+ checkArguments(relation, source);
if (target == null) {
- if (operand == null) {
+ if (source == null) {
throw new IllegalArgumentException(
"The target query cannot be null.");
}
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/AttributeSpans.java b/src/main/java/de/ids_mannheim/korap/query/spans/AttributeSpans.java
index ab0576f..5ee5e75 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/AttributeSpans.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/AttributeSpans.java
@@ -19,28 +19,22 @@
import de.ids_mannheim.korap.query.SpanAttributeQuery;
/**
- * UPDATE THIS!
* Span enumeration of attributes which are term spans with special
- * payload
- * assignments referring to another span (e.g. element/relation span)
- * to which
- * an attribute span belongs. The class is basically a wrapper of
- * Lucene {@link TermSpans} with additional functionality regarding
- * element/relation
+ * payload assignments referring to another span (e.g.
+ * element/relation span) to which an attribute span belongs. The
+ * class is basically a wrapper of Lucene {@link TermSpans} with
+ * additional functionality regarding element/relation
* reference. Element/relation id is annotated ascendingly starting
- * from the
- * left side. <br/>
- * <br/>
+ * from the left side.
+ * <br/><br/>
* The enumeration is ordered firstly by the start position of the
- * attribute and
- * secondly by the element/relation id descendingly. This order helps
- * to match
- * element and attributes faster.
+ * attribute and secondly by the element/relation id descendingly.
+ * This order helps to match element and attributes faster.
*
- * AttributeSpans contain information about the elements they belongs
- * to, thus
- * querying them alone is sufficient to get
- * "any element having a specific attribute".
+ * AttributeSpans have the same start and end positions of the
+ * element/relations they belongs to, thus querying them alone
+ * is sufficient to get "any element having a specific
+ * attribute".
*
* @author margaretha
*/
@@ -59,6 +53,11 @@
private PayloadTypeIdentifier (int value) {
this.value = value;
}
+
+
+ public int getValue () {
+ return value;
+ }
}
protected Logger logger = LoggerFactory.getLogger(AttributeSpans.class);
@@ -101,8 +100,7 @@
/**
* Moves to the next match by checking the candidate match list or
- * setting
- * the list first when it is empty.
+ * setting the list first when it is empty.
*
* @return true if a match is found
* @throws IOException
@@ -132,10 +130,9 @@
/**
* Collects all the attributes in the same start position and sort
- * them by
- * element/relation Id in a reverse order (the ones with the
- * bigger
- * element/relation Id first).
+ * them by element/relation Id in a reverse order (the ones with
+ * the
+ * bigger element/relation Id first).
*
* @throws IOException
*/
@@ -155,8 +152,7 @@
/**
* Creates a CandidateAttributeSpan based on the child span and
- * set the
- * spanId and elementEnd from its payloads.
+ * set the spanId and elementEnd from its payloads.
*
* @param firstSpans
* an AttributeSpans
@@ -169,21 +165,10 @@
byte payloadTypeIdentifier = payloadBuffer.get(0);
short spanId = payloadBuffer.getShort(5);
- // if (payload.get(0).length == 6) {
int end = payloadBuffer.getInt(1);
return new CandidateAttributeSpan(firstSpans, payloadTypeIdentifier,
spanId, end);
-
- // }
- // else if (payload.get(0).length == 10) {
- // start = wrapper.getInt(0);
- // end = wrapper.getInt(4);
- // spanId = wrapper.getShort(8);
- // return new CandidateAttributeSpan(firstSpans, spanId, start, end);
- // }
-
- // throw new NullPointerException("Missing element end in payloads.");
}
@@ -234,14 +219,11 @@
/**
* CandidateAttributeSpan contains information about an Attribute
- * span. All
- * attribute spans occurring in an identical position are
- * collected as
- * CandidateAttributeSpans. The list of these
- * CandidateAttributeSpans are
- * sorted based on the span ids to which the attributes belong to.
- * The
- * attributes with smaller spanIds come first on the list.
+ * span. All attribute spans occurring in an identical position
+ * are collected as CandidateAttributeSpans. The list of these
+ * CandidateAttributeSpans are sorted based on the span ids to
+ * which the attributes belong to. The attributes with smaller
+ * spanIds come first on the list.
*
*/
class CandidateAttributeSpan extends CandidateSpan
@@ -277,14 +259,6 @@
}
- // public CandidateAttributeSpan (Spans span, short spanId, int start,
- // int end) throws IOException {
- // super(span);
- // setSpanId(spanId);
- // this.start = start;
- // this.end = end;
- // }
-
@Override
public int compareTo (CandidateSpan o) {
CandidateAttributeSpan cs = (CandidateAttributeSpan) o;
diff --git a/src/main/java/de/ids_mannheim/korap/query/spans/CandidateSpanComparator.java b/src/main/java/de/ids_mannheim/korap/query/spans/CandidateSpanComparator.java
index c351891..bc50e6d 100644
--- a/src/main/java/de/ids_mannheim/korap/query/spans/CandidateSpanComparator.java
+++ b/src/main/java/de/ids_mannheim/korap/query/spans/CandidateSpanComparator.java
@@ -2,6 +2,14 @@
import java.util.Comparator;
+/**
+ * Compares the positions of two CandidateSpans. The CandidateSpan
+ * with lower document number, start position and end position is
+ * ordered before the other CandidateSpan.
+ *
+ * @author margaretha
+ *
+ */
public class CandidateSpanComparator implements Comparator<CandidateSpan> {
@Override
diff --git a/src/main/resources/log4j.properties b/src/main/resources/log4j.properties
index 1554002..2805e78 100644
--- a/src/main/resources/log4j.properties
+++ b/src/main/resources/log4j.properties
@@ -1,4 +1,4 @@
-log4j.rootLogger = DEBUG, stdout
+log4j.rootLogger = ERROR, stdout
# Queries:
# log4j.logger.de.ids_mannheim.korap.query.SpanNextQuery = TRACE, stdout