Now modeling mono- and multi-lingual resources.

8 files changed, 82 insertions, 20 deletions

diff --git a/src/main/java/com/capitati/omtc/core/resources/IGlossary.java b/src/main/java/com/capitati/omtc/core/resources/IGlossary.java
index c41ad56..795b0f2 100644
--- a/src/main/java/com/capitati/omtc/core/resources/IGlossary.java
+++ b/src/main/java/com/capitati/omtc/core/resources/IGlossary.java
@@ -23,11 +23,11 @@ package com.capitati.omtc.core.resources;
  * 
  * @author ian
  */
-public interface IGlossary extends ITranslationResource {
+public interface IGlossary extends IMultilingualResource {
   /**
    * Retrieve the number of glossary entries.
    *
    * @return The number of entries.
    */
-  int getNumberOfEntries();
+  int getEntryCount();
 }
diff --git a/src/main/java/com/capitati/omtc/core/resources/IMonolingualResource.java b/src/main/java/com/capitati/omtc/core/resources/IMonolingualResource.java
new file mode 100644
index 0000000..9991189
--- /dev/null
+++ b/src/main/java/com/capitati/omtc/core/resources/IMonolingualResource.java
@@ -0,0 +1,18 @@
+package com.capitati.omtc.core.resources;
+
+public interface IMonolingualResource extends IPrimaryResource {
+  /**
+   * Retrieve the language code.
+   *
+   * @return An implementation defined {@link java.lang.String} object that
+   * shall be the language code.
+   */
+  String getLanguage();
+
+  /**
+   * Retrieve the number of sentences in the monolingual resource.
+   *
+   * @return The sentence count for the resource.
+   */
+  int getSentenceCount();
+}
diff --git a/src/main/java/com/capitati/omtc/core/resources/ITranslationResource.java b/src/main/java/com/capitati/omtc/core/resources/IMultilingualResource.java
index 847fe11..ab62522 100644
--- a/src/main/java/com/capitati/omtc/core/resources/ITranslationResource.java
+++ b/src/main/java/com/capitati/omtc/core/resources/IMultilingualResource.java
@@ -27,7 +27,7 @@ import com.capitati.omtc.core.resources.IPrimaryResource;
  *
  * @author ian
  */
-public interface ITranslationResource extends IPrimaryResource {
+public interface IMultilingualResource extends IPrimaryResource {
   /**
    * Retrieve the source language code.
    *
@@ -42,21 +42,21 @@ public interface ITranslationResource extends IPrimaryResource {
    * @return A {@link java.lang.String} array object that shall list the
    * implementation target language codes.
    */
-  String[] getTargetLanguage();
+  String[] getTargetLanguages();
 
   /**
-   * Retrieve the source language word count.
+   * Retrieve the source language sentence count.
    *
-   * @return The number of words in the source language.
+   * @return The number of sentences in the source language.
    */
-  int getSourceWordCount();
+  int getSourceSentenceCount();
 
   /**
-   * Retrieve the target language word counts.
+   * Retrieve the target language sentence counts.
    *
    * @return A {@link java.util.Map} object whose keys shall be the target
-   * language codes, returned by {@link ITranslationResource.getTargetLanguage},
-   * and values the word count for the target language.
+   * language codes, returned by {@link IMultilingualResource.getTargetLanguage},
+   * and values the sentence count for the target language.
    */
-  Map<String, Integer> getTargetWordCounts();
+  Map<String, Integer> getTargetSentenceCounts();
 }
diff --git a/src/main/java/com/capitati/omtc/core/resources/IPrimaryResource.java b/src/main/java/com/capitati/omtc/core/resources/IPrimaryResource.java
index 8750988..87a7050 100644
--- a/src/main/java/com/capitati/omtc/core/resources/IPrimaryResource.java
+++ b/src/main/java/com/capitati/omtc/core/resources/IPrimaryResource.java
@@ -20,7 +20,7 @@ package com.capitati.omtc.core.resources;
 
 /**
  * A resource that is created outside of an MT system and is made available
- * once the MT system has received, e.g. uploading.
+ * once the MT system has received it, say, by uploading a file.
  *
  * @author ian
  */
diff --git a/src/main/java/com/capitati/omtc/core/resources/IResourceReader.java b/src/main/java/com/capitati/omtc/core/resources/IResourceReader.java
index c74539f..f2f7a65 100644
--- a/src/main/java/com/capitati/omtc/core/resources/IResourceReader.java
+++ b/src/main/java/com/capitati/omtc/core/resources/IResourceReader.java
@@ -20,7 +20,28 @@ package com.capitati.omtc.core.resources;
 
 import java.io.IOException;
 
+/**
+ * An abstract resource reader. Implementations of this interface should
+ * ensure that the underlying resource is open and ready for reading before any
+ * calls to {@link IResourceReader.read}. 
+ *
+ * @author ian
+ */
 public interface IResourceReader {
+  /**
+   * Read bytes from the underlying resource into the buffer provided.
+   *
+   * @param buffer - the buffer to read resource bytes in to.
+   * @return The number of bytes read, and written into the buffer.
+   * @throws IOException on error reading the underlying resource.
+   */
   int read(byte[] buffer) throws IOException;
+
+  /**
+   * Close the underlying resource associated with this reader.
+   *
+   * @throws IOException on encountering an error closing the underlying
+   * resource.
+   */
   void close() throws IOException;
 }
diff --git a/src/main/java/com/capitati/omtc/core/resources/IResourceWriter.java b/src/main/java/com/capitati/omtc/core/resources/IResourceWriter.java
index f605e26..93ca9e9 100644
--- a/src/main/java/com/capitati/omtc/core/resources/IResourceWriter.java
+++ b/src/main/java/com/capitati/omtc/core/resources/IResourceWriter.java
@@ -20,7 +20,28 @@ package com.capitati.omtc.core.resources;
 
 import java.io.IOException;
 
+/**
+ * Abstract resource writer. Implementations of this interface should ensure
+ * that the underlying resource is open and ready for writing before any calls
+ * to {@link IResourceWriter.write} are made.
+ *
+ * @author ian
+ */
 public interface IResourceWriter {
+  /**
+   * Write the provided chunk of data to the underlying resource.
+   *
+   * @param chunk - the byte data to write.
+   * @param chunkLength - the number of valid bytes in the buffer.
+   * @throws IOException - on error writing bytes from buffer to the
+   * underlying resource.
+   */
   void write(byte[] chunk, int chunkLength) throws IOException;
+
+  /**
+   * Close any underlying resource.
+   *
+   * @throws IOException - on error closing the underlying resource.
+   */
   void close() throws IOException;
 }
diff --git a/src/main/java/com/capitati/omtc/core/resources/ITranslationMemory.java b/src/main/java/com/capitati/omtc/core/resources/ITranslationMemory.java
index e59c4c1..dab6607 100644
--- a/src/main/java/com/capitati/omtc/core/resources/ITranslationMemory.java
+++ b/src/main/java/com/capitati/omtc/core/resources/ITranslationMemory.java
@@ -23,11 +23,11 @@ package com.capitati.omtc.core.resources;
  *
  * @author ian
  */
-public interface ITranslationMemory extends ITranslationResource {
+public interface ITranslationMemory extends IMultilingualResource {
   /**
    * Retrieves the number of segments from the translation memory.
    *
    * @return The segment count of the translation memory.
    */
-  int getNumberOfSegments();
+  int getSegmentCount();
 }
diff --git a/src/main/java/com/capitati/omtc/core/translation/Translator.java b/src/main/java/com/capitati/omtc/core/translation/Translator.java
index 8f36b04..08335d4 100644
--- a/src/main/java/com/capitati/omtc/core/translation/Translator.java
+++ b/src/main/java/com/capitati/omtc/core/translation/Translator.java
@@ -42,7 +42,9 @@ import com.google.common.base.Predicate;
  *
  * @param <P> - the type of the priority's value.
  */
-public abstract class Translator<V, T extends IPrimaryResource, G extends IPrimaryResource>
+public abstract class Translator<V,
+                                    T extends IPrimaryResource,
+                                    G extends IPrimaryResource>
 implements IDerivedResource {
   private final UUID identifier;
   private final URI location;
@@ -121,7 +123,7 @@ implements IDerivedResource {
    * @param translationObserver - the observer that listens for the translation
    * task to starting and complete.
    * @return A translation ticket.
-   * @throws Exception On an error.
+   * @throws Exception On a scheduling error.
    */
   public abstract TranslationTicket<V, T, G> scheduleTranslation(
       ISession session,
@@ -139,7 +141,7 @@ implements IDerivedResource {
    * @param translationObserver - the observer that listens for the translation
    * task to starting and complete.
    * @return A translation ticket.
-   * @throws Exception On an error.
+   * @throws Exception On a scheduling error.
    */
   public abstract TranslationTicket<V, T, G> scheduleTranslation(
       ISession session,
@@ -150,13 +152,13 @@ implements IDerivedResource {
 
   /**
    * Retrieve the dispensed translation tickets.
-   * 
+   *
+   * @param session - the invoking session.
    * @param filter - a predicate used to filter the translation tickets.
    * @return A {@link java.util.Set} of currently scheduled translation
    * tickets. It is the implementations responsibility to manage the in-flight
    * collection of tickets.
-   *
-   * @throws Exception
+   * @throws Exception On error retrieving translations.
    */
   public abstract Set<TranslationTicket<V, T, G>> retrieveTranslations(
       ISession session,