Adding classification exception and adding extra javadoc

Author: kevto

src/main/java/javax/visrec/ml/classification/AbstractImageClassifier.java

@@ -1,6 +1,7 @@
 package javax.visrec.ml.classification;
 
-import javax.visrec.ml.classification.ImageClassifier;
+import javax.visrec.ImageFactory;
+import javax.visrec.ml.model.ModelProvider;
 import javax.visrec.spi.ServiceProvider;
 import java.awt.image.BufferedImage;
 import java.io.File;
@@ -9,28 +10,28 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
-import javax.visrec.ImageFactory;
-import javax.visrec.ml.model.ModelProvider;
 
 /**
  * Skeleton abstract class to make it easier to implement image classifier.
  * It provides implementation of Classifier interface for images, along with
  * image factory for specific type of images.
  * This class solves the problem of using various implementation of images and machine learning models in Java,
  * and provides standard Classifier API for clients.
- *
+ * <p>
  * By default the type of key in the Map the {@link ImageClassifier} is {@code String}
  *
- * @author Zoran Sevarac
- *
+ * @param <IMAGE_CLASS> class to classify
  * @param <MODEL_CLASS> class of machine learning model
+ * @author Zoran Sevarac
+ * @since 1.0
  */
-public abstract class AbstractImageClassifier<IMAGE_CLASS, MODEL_CLASS> implements ImageClassifier<IMAGE_CLASS>, ModelProvider { // could also implement binary classifier
+public abstract class AbstractImageClassifier<IMAGE_CLASS, MODEL_CLASS> implements ImageClassifier<IMAGE_CLASS>, ModelProvider<MODEL_CLASS> {
 
- private ImageFactory<IMAGE_CLASS> imageFactory; // image factory impl for the specified image class
- private MODEL_CLASS model; // the model could be injected from machine learning container?
+ private final ImageFactory<IMAGE_CLASS> imageFactory;
+ private MODEL_CLASS model;
 
- private float threshold=0.0f; // this should ba a part of every classifier
+ // TODO: this should ba a part of every classifier
+ private float threshold = 0.0f;
 
  protected AbstractImageClassifier(final Class<IMAGE_CLASS> imgCls, final MODEL_CLASS model) {
  final Optional<ImageFactory<IMAGE_CLASS>> optionalImageFactory = ServiceProvider.current()
@@ -48,27 +49,27 @@ public ImageFactory<IMAGE_CLASS> getImageFactory() {
  }
 
  @Override
- public Map<String, Float> classify(File file)   {
+ public Map<String, Float> classify(File file) throws ClassificationException {
  IMAGE_CLASS image;
  try {
  image = imageFactory.getImage(file);
  return classify(image);
  } catch (IOException e) {
- throw new RuntimeException("Couldn't transform input into a BufferedImage", e);
+ throw new ClassificationException("Failed to transform input into a BufferedImage", e);
  }
  }
 
  @Override
- public Map<String, Float> classify(InputStream inputStream) {
+ public Map<String, Float> classify(InputStream inputStream) throws ClassificationException {
  IMAGE_CLASS image;
  try {
  image = imageFactory.getImage(inputStream);
  return classify(image);
  } catch (IOException e) {
- throw new RuntimeException("Couldn't transform input into a BufferedImage", e);
- } 
+ throw new RuntimeException("Failed to transform input into a BufferedImage", e);
+ }
  }
- 
+
  // todo: provide get top 1, 3, 5 results; sort and get
 
  @Override
@@ -77,7 +78,7 @@ public MODEL_CLASS getModel() {
  }
 
  protected final void setModel(MODEL_CLASS model) {
- this.model = Objects.requireNonNull(model, "Model cannot bu null!"); 
+ this.model = Objects.requireNonNull(model, "Model cannot bu null!");
  }
 
  public float getThreshold() {

src/main/java/javax/visrec/ml/classification/ClassificationException.java

@@ -0,0 +1,30 @@
+package javax.visrec.ml.classification;
+
+/**
+ * Exception thrown if anything fails in the execution of a classifier.
+ *
+ * @author Kevin Berendsen
+ * @since 1.0
+ */
+public class ClassificationException extends RuntimeException {
+
+ /**
+ * Creates a new instance of the exception
+ *
+ * @param message additional message of the cause.
+ */
+ public ClassificationException(String message) {
+ super(message);
+ }
+
+ /**
+ * Creates a new instance of the exception
+ *
+ * @param message additional message of the cause.
+ * @param throwable caused by throwable.
+ */
+ public ClassificationException(String message, Throwable throwable) {
+ super(message, throwable);
+ }
+
+}

src/main/java/javax/visrec/ml/classification/Classifier.java

@@ -3,19 +3,18 @@
 /**
  * Classifier answers the question what is the category/type of an input object.
  * Each category/type has corresponding label or class name, which can be String, Enum or custom user defined class.
- * This is a generic classifier interface, that all classifiers should implement, and 
- * it provides a method to classify given instances of some class. 
- * 
+ * This is a generic classifier interface, that all classifiers should implement, and
+ * it provides a method to classify given instances of some class.
+ * <p>
  * Implementations should specify input type <T> of instances that are classified,
  * and type of the returned vales <R>.
- * 
+ * <p>
  * Usually implementations predict category of instances with some probability,
  * and cannot guarantee 100% accuracy.
  *
- * @author Zoran Sevarac
  * @param <T> type of input objects to classify (eg. User, Product, Transaction, Image, etc.)
  * @param <R> type of classification result (String, Enum, custom class).
- * 
+ * @author Zoran Sevarac
  * @see BinaryClassifier
  * @see MultiClassClassifier
  * @see ImageClassifier
@@ -29,7 +28,8 @@ public interface Classifier<T, R> {
  *
  * @param input some instance to classify
  * @return classification results for the specified instance
+ * @throws ClassificationException if the input could not be classified
  */
- R classify(T input);
- 
+ R classify(T input) throws ClassificationException;
+
 }

src/main/java/javax/visrec/ml/classification/ClassifierBuilder.java

@@ -5,10 +5,31 @@
 import java.io.InputStream;
 import java.util.Map;
 
-public interface ImageClassifier<IMAGE_CLASS> extends Classifier<IMAGE_CLASS, Map<String, Float>>{
+/**
+ * Classifier interface specialized in image classification
+ *
+ * @param <IMAGE_CLASS> type of input objects to classify (eg. User, Product, Transaction, Image, etc.)
+ * @author Zoran Sevarac
+ * @since 1.0
+ */
+public interface ImageClassifier<IMAGE_CLASS> extends Classifier<IMAGE_CLASS, Map<String, Float>> {
 
- Map<String, Float> classify(File input);
+ /**
+ * Classify the input and get a map of classification results as output
+ *
+ * @param input {@link File} to use as input
+ * @return {@code Map} with key as classification label and with value as accuracy percentage of likelihood
+ * @throws ClassificationException if the file couldn't be found or classified
+ */
+ Map<String, Float> classify(File input) throws ClassificationException;
 
- Map<String, Float> classify(InputStream input);
+ /**
+ * Classify the input and get a map of classification results as output
+ *
+ * @param input {@link InputStream} to use as input
+ * @return {@code Map} with key as classification label and with value as accuracy percentage of likelihood
+ * @throws ClassificationException if input couldn't be classified
+ */
+ Map<String, Float> classify(InputStream input) throws ClassificationException;
 
 }