Java tutorial
/* * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. */ /* * Loader.java * Copyright (C) 2000-2012 University of Waikato, Hamilton, New Zealand * */ package weka.core.converters; import java.io.File; import java.io.IOException; import java.io.InputStream; import java.io.Serializable; import weka.core.Instance; import weka.core.Instances; import weka.core.RevisionHandler; /** * Interface to something that can load Instances from an input source in some * format. * * @author Mark Hall (mhall@cs.waikato.ac.nz) * @version $Revision$ */ public interface Loader extends Serializable, RevisionHandler { /** * Exception that implementers can throw from getStructure() when they have * not been configured sufficiently in order to read the structure (or data). * * @author Mark Hall (mhall{[at]}pentaho{[dot]}com) */ public static class StructureNotReadyException extends IOException { /** * For Serialization */ private static final long serialVersionUID = 1938493033987645828L; public StructureNotReadyException(String message) { super(message); } } /** The retrieval modes */ public static final int NONE = 0; public static final int BATCH = 1; public static final int INCREMENTAL = 2; /** * Sets the retrieval mode. Note: Some loaders may not be able to implement * incremental loading. * * @param mode the retrieval mode */ void setRetrieval(int mode); /** * Resets the Loader object ready to begin loading. If there is an existing * source, implementations should attempt to reset in such a fashion as to be * able to load from the beginning of the source. * * @throws Exception if Loader can't be reset for some reason. */ void reset() throws Exception; /* * @ public model instance boolean model_structureDetermined * * @ initially: model_structureDetermined == false; * * @ */ /* * @ public model instance boolean model_sourceSupplied * * @ initially: model_sourceSupplied == false; * * @ */ /** * Resets the Loader object and sets the source of the data set to be the * supplied File object. * * @param file the File * @throws IOException if an error occurs support loading from a File. * * <pre> * <jml> * public_normal_behavior * requires: file != null * && (* file exists *); * modifiable: model_sourceSupplied, model_structureDetermined; * ensures: model_sourceSupplied == true * && model_structureDetermined == false; * also * public_exceptional_behavior * requires: file == null * || (* file does not exist *); * signals: (IOException); * </jml> * </pre> */ void setSource(File file) throws IOException; /** * Resets the Loader object and sets the source of the data set to be the * supplied InputStream. * * @param input the source InputStream * @throws IOException if this Loader doesn't support loading from a File. */ void setSource(InputStream input) throws IOException; /** * Determines and returns (if possible) the structure (internally the header) * of the data set as an empty set of instances. * * @return the structure of the data set as an empty set of Instances * @throws IOException if there is no source or parsing fails * * <pre> * <jml> * public_normal_behavior * requires: model_sourceSupplied == true * && model_structureDetermined == false * && (* successful parse *); * modifiable: model_structureDetermined; * ensures: \result != null * && \result.numInstances() == 0 * && model_structureDetermined == true; * also * public_exceptional_behavior * requires: model_sourceSupplied == false * || (* unsuccessful parse *); * signals: (IOException); * </jml> * </pre> */ Instances getStructure() throws IOException; /** * Return the full data set. If the structure hasn't yet been determined by a * call to getStructure then the method should do so before processing the * rest of the data set. * * @return the full data set as an Instances object * @throws IOException if there is an error during parsing or if * getNextInstance has been called on this source (either * incremental or batch loading can be used, not both). * * <pre> * <jml> * public_normal_behavior * requires: model_sourceSupplied == true * && (* successful parse *); * modifiable: model_structureDetermined; * ensures: \result != null * && \result.numInstances() >= 0 * && model_structureDetermined == true; * also * public_exceptional_behavior * requires: model_sourceSupplied == false * || (* unsuccessful parse *); * signals: (IOException); * </jml> * </pre> */ Instances getDataSet() throws IOException; /** * Read the data set incrementally---get the next instance in the data set or * returns null if there are no more instances to get. If the structure hasn't * yet been determined by a call to getStructure then method should do so * before returning the next instance in the data set. * * If it is not possible to read the data set incrementally (ie. in cases * where the data set structure cannot be fully established before all * instances have been seen) then an exception should be thrown. * * @param structure the dataset header information, will get updated in case * of string or relational attributes * @return the next instance in the data set as an Instance object or null if * there are no more instances to be read * @throws IOException if there is an error during parsing or if getDataSet * has been called on this source (either incremental or batch * loading can be used, not both). */ Instance getNextInstance(Instances structure) throws IOException; }