Changeset 5749 for SRUClient

Timestamp:

10/28/14 13:42:26 (10 years ago)

Author:

Oliver Schonefeld

Message:

• update javadoc

Location:

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs

Files:

• ClarinFCSClientBuilder.java (modified) (8 diffs)
• DataView.java (modified) (1 diff)
• DataViewGenericDOM.java (modified) (1 diff)
• DataViewGenericString.java (modified) (1 diff)
• DataViewHits.java (modified) (4 diffs)
• DataViewParser.java (modified) (1 diff)
• DataViewParserGenericDOM.java (modified) (1 diff)
• DataViewParserGenericString.java (modified) (1 diff)
• DataViewParserHits.java (modified) (1 diff)
• DataViewParserKWIC.java (modified) (1 diff)
• LegacyClarinFCSRecordDataParser.java (modified) (1 diff)

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/ClarinFCSClientBuilder.java

@@ -57 +57 @@
 
     /**
-     * Parse unknown data views into a DOM.
+     * Configure client to parse unknown Data Views into a DOM representation.
      *
      * @return this {@link ClarinFCSClientBuilder} instance
      * @see DataViewParserGenericDOM
+     * @see DataViewGenericDOM
      */
     public ClarinFCSClientBuilder unknownDataViewAsDOM() {
@@ -69 +70 @@
 
     /**
-     * Parse unknown data views into a String.
+     * Configure client to parse unknown Data Views into a String
+     * representation.
      *
      * @return this {@link ClarinFCSClientBuilder} instance
      * @see DataViewParserGenericString
+     * @see DataViewGenericString
      */
     public ClarinFCSClientBuilder unknownDataViewAsString() {
@@ -99 +102 @@
 
     /**
-     * Enable support for legacy CLARIN-FCS endpoints.
+     * Configure client to enable support for legacy CLARIN-FCS endpoints.
      *
      * @return this {@link ClarinFCSClientBuilder} instance
@@ -110 +113 @@
 
     /**
-     * Disable support for legacy CLARIN-FCS endpoints.
+     * Configure client to disable support for legacy CLARIN-FCS endpoints.
      *
      * @return this {@link ClarinFCSClientBuilder} instance
@@ -184 +187 @@
 
     /**
-     * Register a data view parser.
+     * Register a Data View parser.
      *
      * @param parser
@@ -191 +194 @@
      * @throws IllegalArgumentException
      *             if an error occurred while registering the data view parser
+     * @see DataViewParser
      */
     public ClarinFCSClientBuilder registerDataViewParser(DataViewParser parser) {
@@ -200 +204 @@
             throw new IllegalArgumentException("parsers of type '" +
                     parser.getClass().getName() +
-                    "' should not be added manually");
+                    "' cannot be added manually");
         }
 
@@ -257 +261 @@
 
 
+    @SuppressWarnings("deprecation")
     private List<DataViewParser> finalizeDataViewParsers() {
         final List<DataViewParser> result =

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataView.java

@@ -18 +18 @@
 
 /**
- * Base class for DataView implementations according to the CLARIN-FCS record
+ * Base class for Data View implementations according to the CLARIN-FCS record
  * schema.
  */

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewGenericDOM.java

@@ -21 +21 @@
 
 /**
- * A generic DataView implementation that stores the content as a DOM document.
+ * A generic Data View implementation that stores the content of the Data View
+ * as a DOM document.
  */
 public class DataViewGenericDOM extends DataView {

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewGenericString.java

@@ -18 +18 @@
 
 /**
- * A generic DataView implementation that stores the content as a String.
+ * A generic Data View implementation that stores the content of a Data View as
+ * a String.
  */
 public class DataViewGenericString extends DataView {

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewHits.java

@@ -1 +1 @@
 package eu.clarin.sru.client.fcs;
 
+/**
+ * A Data View implementation that stores the content of a HITS Data View.
+ */
 public class DataViewHits extends DataView {
     /**
@@ -55 +58 @@
 
 
+    /**
+     * Get the total number of hits in the result.
+     * @return the number of hits
+     */
     public int getHitCount() {
         return max_offset;
@@ -60 +67 @@
 
 
+    /**
+     * Get the text content of the hit. Usually this is complete sentence.
+     * 
+     * @return the text content of the hit
+     */
     public String getText() {
         return text;
@@ -65 +77 @@
 
 
+    /**
+     * Get the offsets pointing to range in the text content that yield the hit.
+     * 
+     * @param idx
+     *            the hit to retrieve. Must be larger than <code>0</code> and
+     *            smaller than the result of {@link #getHitCount()}.
+     * @return An array of two elements. The first array element is the start
+     *         offset, the second array element is the end offset of the hit
+     *         range.
+     * @throws ArrayIndexOutOfBoundsException
+     *             of the <code>idx</code> argument is out of bounds.
+     */
     public int[] getHitOffsets(int idx) {
         if (idx < 0) {
-            throw new IllegalArgumentException("idx < 0");
+            throw new ArrayIndexOutOfBoundsException("idx < 0");
         }
         if (idx < max_offset) {

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewParser.java

@@ -24 +24 @@
 
 /**
- * Base class for implementing parsers for parsing a specific DataView in a
- * CLARIN-FCS record.
- * <p>If multiple record parsers support a certain type, the one
- * with the highest priority is selected.</p>
+ * Base class for implementing parsers for parsing a specific Data View embedded
+ * in a CLARIN-FCS record.
+ * <p>
+ * If multiple record parsers support a certain type, the one with the highest
+ * priority is selected.
+ * </p>
  */
 public interface DataViewParser {

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewParserGenericDOM.java

@@ -35 +35 @@
 
 
+/**
+ * An implementation of a Data View parser that stores the content of a Data
+ * View in DOM representation.
+ * 
+ * @see DataViewGenericDOM
+ */
 public class DataViewParserGenericDOM implements DataViewParser {
     private static class TransformHelper {

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewParserGenericString.java

@@ -27 +27 @@
 
 
+/**
+ * An implementation of a DataView parser that stores the content of a Data
+ * Views in String representation.
+ * 
+ * @see DataViewGenericString
+ */
 public class DataViewParserGenericString implements DataViewParser {
     private static final XMLOutputFactory factory =

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewParserHits.java

@@ -13 +13 @@
 
 
+/**
+ * An implementation of a Data View parser that parses HITS Data Views. This
+ * parser expects input that conforms to the CLARIN-FCS specification for the
+ * HITS Data View.
+ *
+ * @see DataViewHits
+ */
 public final class DataViewParserHits implements DataViewParser {
     private static final int OFFSET_CHUNK_SIZE = 8;

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/DataViewParserKWIC.java

@@ -26 +26 @@
 import eu.clarin.sru.client.XmlStreamReaderUtils;
 
+
+/**
+ * An implementation of a Data View parser that parses legacy KWIC Data Views.
+ * The input will automatically be upgraded to a HITS Data View and an instance
+ * of {@link DataViewHits} will be returned.
+ *
+ * @see DataViewHits
+ * @deprecated Use only to talk to legacy clients. Endpoints should upgrade to
+ *             recent CLARIN-FCS specification.
+ */
+@Deprecated
 public class DataViewParserKWIC implements DataViewParser {
     private static final String FCS_KWIC_NS = "http://clarin.eu/fcs/1.0/kwic";

SRUClient/trunk/src/main/java/eu/clarin/sru/client/fcs/LegacyClarinFCSRecordDataParser.java

@@ -13 +13 @@
  * A record data parse to parse legacy records.
  *
- * @deprecated Use only to talk to legacy clients
+ * @deprecated Use only to talk to legacy clients. Endpoints should upgrade to
+ *             recent CLARIN-FCS specification.
  */
 @Deprecated