Changeset 5546 for FCSSimpleEndpoint/trunk/src/main/java/eu/clarin/sru/server/fcs/XMLStreamWriterHelper.java

Timestamp:

08/09/14 20:45:17 (10 years ago)

Author:

Oliver Schonefeld

Message:

• support new FCS specification (with some backwards compatibility for old spec)

HEADS UP: not yet ready for release; needs more testing

File:

• FCSSimpleEndpoint/trunk/src/main/java/eu/clarin/sru/server/fcs/XMLStreamWriterHelper.java (modified) (6 diffs)

FCSSimpleEndpoint/trunk/src/main/java/eu/clarin/sru/server/fcs/XMLStreamWriterHelper.java

@@ -8 +8 @@
  * This class provides several helper methods for writing records in the
  * CLARIN-FCS record schema. These methods <em>do not</em> cover the full
- * spectrum of all variations of records that are permitted by the CLARIN FCS
+ * spectrum of all variations of records that are permitted by the CLARIN-FCS
  * specification.
  *
  * @see <a
- *      href="https://trac.clarin.eu/wiki/FCS-specification#SearchRetrieveOperation">
- *      CLARIN FCS specification, section "SearchRetrieve Operation"</a>
+ *      href="https://trac.clarin.eu/wiki/FCS/Specification">
+ *      CLARIN FCS specification, section "Operation searchRetrieve"</a>
  */
 public final class XMLStreamWriterHelper {
@@ -23 +23 @@
     private static final String FCS_KWIC_MIMETYPE =
             "application/x-clarin-fcs-kwic+xml";
+    private static final String FCS_HITS_NS =
+            "http://clarin.eu/fcs/dataview/hits";
+    private static final String FCS_HITS_PREFIX = "hits";
+    private static final String FCS_HITS_MIMETYPE =
+            "application/x-clarin-fcs-hits+xml";
 
 
@@ -205 +210 @@
      * @throws XMLStreamException
      *             if an error occurred
-     */
+     * @deprecated The the HITS data view instead.
+     */
+    @Deprecated
     public static void writeKWICDataView(XMLStreamWriter writer, String left,
             String keyword, String right) throws XMLStreamException {
         if (writer == null) {
             throw new NullPointerException("writer == null");
+        }
+        if (keyword == null) {
+            throw new NullPointerException("keyword == null");
         }
 
@@ -246 +256 @@
      * Convince method for writing a record with a KWIC data view. The following
      * code (arguments omitted) would accomplish the same result:
+     *
      * <pre>
      * ...
@@ -272 +283 @@
      * @throws XMLStreamException
      *             if an error occurred
-     */
+     * @deprecated The the HITS data view instead.
+     */
+    @Deprecated
     public static void writeResourceWithKWICDataView(XMLStreamWriter writer,
             String pid, String ref, String left, String keyword, String right)
@@ -285 +298 @@
     }
 
+
+
+    /**
+     * Convince method to write a simple HITS data view. It automatically
+     * performs the calls to
+     * {@link #writeStartDataView(XMLStreamWriter, String)} and
+     * {@link #writeEndDataView(XMLStreamWriter)}.
+     *
+     * @param writer
+     *            the {@link XMLStreamWriter} to be used
+     * @param left
+     *            the left context of the hit or <code>null</code> if not
+     *            applicable
+     * @param hit
+     *            the actual hit, that will be highlighted
+     * @param right
+     *            the right context of the hit or <code>null</code> if not
+     *            applicable
+     * @throws XMLStreamException
+     *             if an error occurred
+     */
+    public static void writeHitsDataView(XMLStreamWriter writer, String left,
+            String hit, String right) throws XMLStreamException {
+        if (writer == null) {
+            throw new NullPointerException("writer == null");
+        }
+        if (hit == null) {
+            throw new NullPointerException("hit == null");
+        }
+
+        writeStartDataView(writer, FCS_HITS_MIMETYPE);
+
+        // actual "hits" data view
+        writer.setPrefix(FCS_HITS_PREFIX, FCS_HITS_NS);
+        writer.writeStartElement(FCS_HITS_NS, "Result");
+        writer.writeNamespace(FCS_HITS_PREFIX, FCS_HITS_NS);
+
+        if ((left != null) && !left.isEmpty()) {
+            writer.writeCharacters(left);
+        }
+
+        writer.writeStartElement(FCS_HITS_NS, "Hit");
+        writer.writeCharacters(hit);
+        writer.writeEndElement(); // "Hit" element
+
+        if ((right != null) && !right.isEmpty()) {
+            writer.writeCharacters(right);
+        }
+
+        writer.writeEndElement(); // "Result" element
+
+        writeEndDataView(writer);
+    }
+
+
+    /**
+     * Convince method for writing a record with a KWIC data view. The following
+     * code (arguments omitted) would accomplish the same result:
+     *
+     * <pre>
+     * ...
+     * writeStartResource(...);
+     * writeHitsDataView(...);
+     * writeEndResource(...);
+     * ...
+     * </pre>
+     *
+     * @param writer
+     *            the {@link XMLStreamWriter} to be used
+     * @param pid
+     *            the persistent identifier of this resource or
+     *            <code>null</code>, if not applicable
+     * @param ref
+     *            the reference of this resource or <code>null</code>, if not
+     *            applicable
+     * @param left
+     *            the left context of the hit or <code>null</code> if not
+     *            applicable
+     * @param hit
+     *            the actual hit, that will be highlighted
+     * @param right
+     *            the right context of the hit or <code>null</code> if not
+     *            applicable
+     * @throws XMLStreamException
+     *             if an error occurred
+     */
+    public static void writeResourceWithHitsDataView(XMLStreamWriter writer,
+            String pid, String ref, String left, String hit, String right)
+            throws XMLStreamException {
+        if (writer == null) {
+            throw new NullPointerException("writer == null");
+        }
+
+        writeStartResource(writer, pid, ref);
+        writeHitsDataView(writer, left, hit, right);
+        writeEndResource(writer);
+    }
+
+
+    /**
+     * Convince method to write a simple HITS data view. It automatically
+     * performs the calls to
+     * {@link #writeStartDataView(XMLStreamWriter, String)} and
+     * {@link #writeEndDataView(XMLStreamWriter)}.
+     *
+     * @param writer
+     *            the {@link XMLStreamWriter} to be used
+     * @param text
+     *            the text content of the hit
+     * @param hits
+     *            an even-element array containing tuples for the hit markers in
+     *            the text content
+     * @param secondIsLength
+     *            if <code>true</code> the second element of each tuple in this
+     *            <code>hits</code> array is interpreted as an length; if
+     *            <code>false</code> it is interpreted as an end-offset
+     * @throws XMLStreamException
+     *             if an error occurred
+     */
+    public static void writeHitsDataView(XMLStreamWriter writer, String text,
+            int[] hits, boolean secondIsLength) throws XMLStreamException {
+        if (writer == null) {
+            throw new NullPointerException("writer == null");
+        }
+        if (text == null) {
+            throw new NullPointerException("text == null");
+        }
+        if (hits == null) {
+            throw new NullPointerException("text == null");
+        }
+        if ((hits.length == 0) || ((hits.length % 2) != 0)) {
+            throw new NullPointerException("length of hits array must " +
+                    "contain an even number of elements");
+        }
+
+        writeStartDataView(writer, FCS_HITS_MIMETYPE);
+
+        // actual "hits" data view
+        writer.setPrefix(FCS_HITS_PREFIX, FCS_HITS_NS);
+        writer.writeStartElement(FCS_HITS_NS, "Result");
+        writer.writeNamespace(FCS_HITS_PREFIX, FCS_HITS_NS);
+
+        int pos = 0;
+        for (int i = 0; i < hits.length; i += 2) {
+            int start  = hits[i];
+            int end    = hits[i + 1];
+
+            if ((start < 0) && (start > text.length())) {
+                throw new IllegalArgumentException("start index out of " +
+                        "bounds: start=" + start);
+            }
+            if (secondIsLength) {
+                if (end < 1) {
+                    throw new IllegalArgumentException(
+                            "length must be larger than 0: length = " + end);
+                }
+                end += start;
+            }
+            if (start >= end) {
+                throw new IllegalArgumentException("end offset must be " +
+                        "larger then start offset: start=" + start +
+                        ", end="+ end);
+            }
+
+            if (start > pos) {
+                String s = text.substring(pos, start);
+                writer.writeCharacters(s);
+            }
+            writer.writeStartElement(FCS_HITS_NS, "Hit");
+            writer.writeCharacters(text.substring(start, end));
+            writer.writeEndElement(); // "Hits" element
+            pos = end;
+        }
+        if (pos < text.length() - 1) {
+            writer.writeCharacters(text.substring(pos));
+        }
+
+        writer.writeEndElement(); // "Result" element
+
+        writeEndDataView(writer);
+    }
+
+
+    /**
+     * Convince method to write a simple HITS data view. It automatically
+     * performs the calls to
+     * {@link #writeStartDataView(XMLStreamWriter, String)} and
+     * {@link #writeEndDataView(XMLStreamWriter)}.
+     *
+     * <pre>
+     * ...
+     * writeStartResource(...);
+     * writeHitsDataView(...);
+     * writeEndResource(...);
+     * ...
+     * </pre>
+     *
+     * @param writer
+     *            the {@link XMLStreamWriter} to be used
+     * @param pid
+     *            the persistent identifier of this resource or
+     *            <code>null</code>, if not applicable
+     * @param ref
+     *            the reference of this resource or <code>null</code>, if not
+     *            applicable
+     * @param text
+     *            the text content of the hit
+     * @param hits
+     *            an even-element array containing tuples for the hit markers in
+     *            the text content
+     * @param secondIsLength
+     *            if <code>true</code> the second element of each tuple in this
+     *            <code>hits</code> array is interpreted as an length; if
+     *            <code>false</code> it is interpreted as an end-offset
+     * @throws XMLStreamException
+     *             if an error occurred
+     */
+    public static void writeResourceWithHitsDataView(XMLStreamWriter writer,
+            String pid, String ref, String text,
+            int[] hits, boolean secondIsLength)
+            throws XMLStreamException {
+        if (writer == null) {
+            throw new NullPointerException("writer == null");
+        }
+
+        writeStartResource(writer, pid, ref);
+        writeHitsDataView(writer, text, hits, secondIsLength);
+        writeEndResource(writer);
+    }
+
 } // class XMLStreamWriterHelper