001/**
002 * Copyright (C) 2007 - 2016, Jens Lehmann
003 *
004 * This file is part of DL-Learner.
005 *
006 * DL-Learner is free software; you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation; either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * DL-Learner is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
018 */
019package org.dllearner.core;
020
021import org.semanticweb.owlapi.model.AxiomType;
022import org.semanticweb.owlapi.model.OWLAxiom;
023
024/**
025 * The AxiomLearningProgressMonitor interface should be implemented by objects that
026 * wish to monitor the progress of an axiom learning algorithm. The learning algorithm whose progress is
027 * being monitored will call the methods on this interface. The progress monitor
028 * is designed to monitor long running learning algorithm tasks such as loading,
029 * preprocessing and learning. <br>
030 * Tasks are executed sequentially. Nested tasks are not supported. <br>
031 * The general contract is that the learning algorithm will call
032 * {@link #learningStarted(AxiomType)}, then call either
033 * {@link #learningTaskBusy(AxiomType)} or {@link #learningProgressChanged(AxiomType, int, int)}
034 * any number of times and finally call {@link #learningStopped(AxiomType)} when the
035 * task ends or has been interrupted. This cycle may then be repeated.
036 * 
037 * 
038 * @author Lorenz Buehmann
039 *
040 */
041public interface AxiomLearningProgressMonitor {
042        /**
043     * A standard name for the task of loading a reasoner with axioms. Note that
044     * there is no guarantee that the reasoner will use this name for loading.
045     */
046    String LOADING = "Loading";
047    /**
048     * A standard name for the task of computing the class hierarchy. Note that
049     * there is no guarantee that the reasoner will use this name for the task
050     * of computing the class hierarchy.
051     */
052    String PREPROCESSING = "Preprocessing";
053    /**
054     * A standard name for the task of computing the types of individual. Note
055     * that there is no guarantee that the reasoner will use this name for the
056     * task of realising.
057     */
058    String LEARNING = "Learning";
059   
060
061    /**
062     * Indicates that some learning algorithm has started. When the learning algorithm has
063     * finished the {@link #learningStopped(AxiomType)} method will be called. Once
064     * this method has been called it will not be called again unless the
065     * {@link #learningStopped(AxiomType)} method has been called. <br>
066     * Note that this method may be called from a thread that is not the event
067     * dispatch thread.
068     * 
069     * @param axiomType
070     *        The type of axiom
071     */
072    void learningStarted(AxiomType<? extends OWLAxiom> axiomType);
073
074    /**
075     * Indicates that a previously started learning algorithm has now stopped. This method will
076     * only be called after the {@link #learningStarted(AxiomType)} method has
077     * been called.<br>
078     * Note that this method may be called from a thread that is not the event
079     * dispatch thread.
080     */
081    void learningStopped(AxiomType<? extends OWLAxiom> axiomType);
082
083    /**
084     * Indicates that the learning algorithm is part way through its task. This method
085     * will only be called after the {@link #learningStarted(AxiomType)} method
086     * has been called. It will not be called after the
087     * {@link #learningStopped(AxiomType)} method has been called. <br>
088     * Note that this method may be called from a thread that is not the event
089     * dispatch thread.
090     * 
091     * @param value
092     *        The value or portion of the learning algorithm task completed
093     * @param max
094     *        The total size of the learning algorithm task
095     */
096    void learningProgressChanged(AxiomType<? extends OWLAxiom> axiomType, int value, int max);
097
098    /**
099     * Indicates that the learning algorithm is busy performing a task whose size cannot
100     * be determined. This method will only be called after the
101     * {@link #learningStarted(AxiomType)} method has been called. It will not
102     * be called after the {@link #learningStopped(AxiomType)} method has been
103     * called. <br>
104     * Note that this method may be called from a thread that is not the event
105     * dispatch thread.
106     */
107    void learningTaskBusy(AxiomType<? extends OWLAxiom> axiomType);
108    
109    void learningFailed(AxiomType<? extends OWLAxiom> axiomType);
110}