1   /*
2    *  Copyright (c) 1998-2001, The University of Sheffield.
3    *
4    *  This file is part of GATE (see http://gate.ac.uk/), and is free
5    *  software, licenced under the GNU Library General Public License,
6    *  Version 2, June 1991 (in the distribution as file licence.html,
7    *  and also available at http://gate.ac.uk/gate/licence.html).
8    *
9    *  Valentin Tablan 21/11/2002
10   *
11   *  $Id: MLEngine.java,v 1.2 2002/11/27 15:13:31 valyt Exp $
12   *
13   */
14  package gate.creole.ml;
15  
16  import java.util.*;
17  import java.io.*;
18  
19  import org.jdom.*;
20  
21  import gate.*;
22  import gate.util.*;
23  import gate.creole.ExecutionException;
24  
25  /**
26   * This interface is used for wrappers to Machine Learning engines.
27   * All classes implementing this interface should have a public constructor
28   * that takes no parameters.
29   */
30  public interface MLEngine {
31  
32    /**
33     * Sets the options from an XML JDom element.
34     * @param options the JDom element containing the options from the
35     * configuration.
36     */
37    public void setOptions(Element options);
38  
39    /**
40     * Adds a new training instance to the dataset.
41     * @param attributes the list of attributes describing the instance. The
42     * elements in the list are String values that need to be interpreted
43     * according to the dataset definition: for nominal attributes the values will
44     * used as they are; for numeric attributes the values will be converted to
45     * double.
46     */
47    public void addTrainingInstance(List attributes)throws ExecutionException;
48  
49    /**
50     * Sets the definition for the dataset used.
51     * @param definition
52     */
53    public void setDatasetDefinition(DatasetDefintion definition);
54  
55    /**
56     * Classifies a new instance.
57     * @param attributes the list of attributes describing the instance. The
58     * elements in the list are Object values that need to be interpreted
59     * according to the dataset definition. The value for the class element will
60     * be arbitrary.
61     * @return a String value for nominal and boolean attributes and a Double
62     * value for numeric attributes.
63     */
64    public Object classifyInstance(List attributes)throws ExecutionException;
65  
66    /**
67     * This method will be called after an engine is created and has its dataset
68     * and options set. This allows the ML engine to initialise itself in
69     * preparation of being used.
70     *
71     * @throws GateException
72     */
73    public void init() throws GateException;
74  
75    /**
76     * Registers the PR using the engine with the engine itself.
77     * @param pr the processing resource that owns this engine.
78     */
79    public void setOwnerPR(ProcessingResource pr);
80  }