de.learnlib.api.query.Query Maven / Gradle / Ivy
Show all versions of learnlib-api Show documentation
/* Copyright (C) 2013-2020 TU Dortmund
* This file is part of LearnLib, http://www.learnlib.de/.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package de.learnlib.api.query;
import java.util.Objects;
import de.learnlib.api.algorithm.LearningAlgorithm;
import de.learnlib.api.oracle.MembershipOracle;
import net.automatalib.automata.fsa.DFA;
import net.automatalib.automata.transducers.MealyMachine;
import net.automatalib.words.Word;
import org.checkerframework.checker.nullness.qual.Nullable;
/**
* A query is the basic form of interaction between a {@link LearningAlgorithm learner} and a {@link MembershipOracle
* (membership) oracle}, or teacher.
*
* In LearnLib, queries are performed in a callback-like fashion: an oracle does not return the responses to the
* queries, but rather invokes the {@link #answer(Object)} method on the query objects it was provided with. This allows
* for implementing queries which directly react to an answered query (e.g., by modifying some internal data structure),
* without the need for buffering answers. It also allows for a more efficient parallel processing of queries, as there
* is no need for maintaining a common (synchronized) result data structure such as a map. However, this means that a
* learner cannot rely on the {@link #answer(Object)} method of a query being called from the same thread which invoked
* {@link MembershipOracle#processQueries(java.util.Collection)}. If this causes concurrency issues, a safe choice is to
* use queries of class {@link DefaultQuery}, which simply store the response and make it accessible via {@link
* DefaultQuery#getOutput()} for processing after the {@link MembershipOracle#processQueries(java.util.Collection)} call
* returns, guaranteeing thread-safety.
*
* Conceptually, a query is divided into a {@link #getPrefix() prefix} and a {@link #getSuffix()} suffix. The prefix
* part of a query identifies a state in the (unknown) target system, whereas the suffix is the "experiment" which is
* conducted on the system starting from the state to which it was transferred by the prefix. While the prefix
* influences the response of the target system to a query, the answer is the directly observable reaction to
* executing the suffix.
*
* Example 1: when learning {@link MealyMachine Mealy machines}, the prefix transfers the target system to a
* certain state. The outputs produced by the system while executing the prefix are not part of the answer, as
* the role of the prefix is limited to reaching a certain state. The reaction of the target system consists of the
* output word produced while executing the suffix. Therefore, in the setting of Mealy machine learning, a valid oracle
* will call the {@link #answer(Object)} method with a word of the same length as the suffix.
*
* Example 2: when learning {@link DFA}s, the reaction of the target system is fully determined by the state
* reached by an input word. Since both prefix and suffix have the same effect on producing this output (by transferring
* the system to a certain state), the response will always be a single {@link Boolean}, and, furthermore, for every
* input word {@code w}, the response to a query will always be the same regardless of the subdivision of {@code w = uv}
* into prefix {@code u} and suffix {@code v} (including the corner cases u = ε and v =
* ε).
*
* @param
* input symbol type
* @param
* output domain type
*
* @author Malte Isberner
*/
public abstract class Query {
private int hashCode;
/**
* Answers the query. This method should be called by a {@link MembershipOracle}, and only once per query to
* process. Calling this method more than once may result in undefined behavior, possibly (but not necessarily)
* throwing an exception.
*
* @param output
* the output, i.e., the directly observable response to the query's suffix (cf. {@link Query main
* documentation})
*/
public abstract void answer(D output);
/**
* Retrieves the input word of this query. The input word corresponding to a query is the concatenation of its
* prefix and suffix.
*
* @return the input word of this query
*/
public Word getInput() {
return getPrefix().concat(getSuffix());
}
/**
* Returns the prefix part of this query. The prefix of a query is responsible for transferring the system into a
* certain state, but (apart from that) does not directly influence the output.
*
* @return the prefix of this query
*/
public abstract Word getPrefix();
/**
* Returns the suffix part of this query. The suffix of a query is the experiment performed on the system when in
* the state it was transferred into by the prefix, and thus directly influences the output.
*
* @return the suffix of this query
*/
public abstract Word getSuffix();
@Override
public final int hashCode() {
if (hashCode != 0) {
return hashCode;
}
hashCode = 1;
hashCode = 31 * hashCode + Objects.hashCode(getPrefix());
hashCode = 31 * hashCode + Objects.hashCode(getSuffix());
return hashCode;
}
@Override
public final boolean equals(@Nullable Object o) {
if (this == o) {
return true;
}
if (!(o instanceof Query)) {
return false;
}
final Query that = (Query) o;
return Objects.equals(getPrefix(), that.getPrefix()) && Objects.equals(getSuffix(), that.getSuffix());
}
/**
* Returns the string representation of this query.
*
* @return A string of the form {@code "Query[|]"} for queries not containing an answer or {@code
* "Query[| / ]"} if an answer may be specified.
*/
@Override
public String toString() {
return "Query[" + getPrefix() + '|' + getSuffix() + ']';
}
}