source: TraumaOntologies/src/main/java/tudelft/healthpsychology/traumaontologies/answerstate/AnswerState.java

package tudelft.healthpsychology.traumaontologies.answerstate;

import java.util.Collection;

import com.fasterxml.jackson.annotation.JsonAutoDetect;
import com.fasterxml.jackson.annotation.JsonAutoDetect.Visibility;
import com.fasterxml.jackson.annotation.JsonSubTypes;
import com.fasterxml.jackson.annotation.JsonTypeInfo;

import tudelft.healthpsychology.traumaontologies.questiontypes.TypedQuestion;
import tudelft.utilities.tree.Tree;

/**
 * <o> Defines (possibly partial) answer to a question and the answer type
 * needed to bring it closer to a full answer. An AnswerState contains
 * references to node labels in a {@link Tree}. The tree structure
 * (children/parent relations, node labels and node attributes) contains the
 * detailed information for the answerstate on how to proceed.
 * </p>
 * <o> All {@link AnswerState}s work like this: provide answers (just a string)
 * to all the questions until there are no more questions.
 * </p>
 * <o> To get the next question, call {@link #getOptions()} which gives you the
 * question and the allowed answers. Call {@link #with(String)} with the answer
 * string and update to the returned state. Repeat until {@link #getOptions()}
 * returns null.
 * </p>
 * <o> All AnswerState implementations are immutable,
 * </p>
 */
@JsonAutoDetect(fieldVisibility = Visibility.ANY, getterVisibility = Visibility.NONE, setterVisibility = Visibility.NONE)
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.WRAPPER_OBJECT)
@JsonSubTypes({ @JsonSubTypes.Type(value = AnswersBreathFirstState.class),
                @JsonSubTypes.Type(value = AnswersDepthFirstState.class),
                @JsonSubTypes.Type(value = AnswerStateExplanationDecorator.class),
                @JsonSubTypes.Type(value = ListOfAnswersState.class),
                @JsonSubTypes.Type(value = OntoPropAnswerState.class),
                @JsonSubTypes.Type(value = PropertiesAnswerState.class) })
public interface AnswerState {

        /**
         * @param tree the tree containing the node(s) relevant for this state.
         * @return the type of the possible answer(s). null if this is the final
         *         state.
         */
        TypedQuestion getOptions(
                        Tree<String, Collection<Property>, OntologyNode> tree);

        /**
         * 
         * @param answer the next answer. In some cases "null" is accepted, as the
         *               "other", "not applicable" or "don't know" option.
         * @param tree   the tree containing the node(s) relevant for this state.
         * @return a new state representing the situation after the answer was given
         * @throws IllegalArgumentException if the given answer does not fit : see
         *                                  {@link TypedQuestion#fits(String)}
         */
        AnswerState with(String answer,
                        Tree<String, Collection<Property>, OntologyNode> tree);

}