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);

}