!!! Running a d3web [Session|https://isci.informatik.uni-wuerzburg.de/javadoc/d3web/de/d3web/core/session/Session.html]

Once, you have created a [KnowledgeBase|https://isci.informatik.uni-wuerzburg.de/javadoc/d3web/de/d3web/core/knowledge/KnowledgeBase.html] instance (for example, by [Loading a knowledge base|How-To Load a Knowledge Base]), you can run a problem-solving session.
During a problem-solving session you enter Question-Value pairs ([Fact|https://isci.informatik.uni-wuerzburg.de/javadoc/d3web/de/d3web/core/session/blackboard/Fact.html]) and the system will derive appropriate solutions for the entered facts.

!! Creating a new Session
Sessions are represented by instances of {{Session}}.
Use the {{SessionFactory}} to quickly create a new {{Session}} instance for the {{KnowledgeBase}} instance:

%%prettify 
{{{
Session session = SessionFactory.createSession(knowledgeBase);
}}}
/%

!! Retrieve the next reasonable question

The [Interview|https://isci.informatik.uni-wuerzburg.de/javadoc/d3web/de/d3web/core/session/interviewmanager/Interview.html], instantiated with the Session, determines the next question to be presented to the user. More precisely, a {{FormStrategy}} computes the next {{From}} that is presented in the dialog. 
A Form consists of a title and an {{interviewObject}} (a Question of a QContainer):

%%prettify 
{{{
Form form = session.getInterview().nextForm();
InterviewObject interviewObject = form.getInterviewObject();
}}}
/%

To retrieve a single question contained in the {{Form}} you may use the {{NextUnansweredQuestionFormStrategy}}. This can be explicitly set by

%%prettify 
{{{
session.getInterviewManager().setFormStrategy(new NextUnansweredQuestionFormStrategy());
}}}
/%



!! Entering Facts to the Session

Next, we subsequently add facts to the session. When already having the appropriate instances of {{Question}} and {{Value}}, respectively, we are able to simply set the value by 

%%prettify 
{{{
Fact fact = FactFactory.createFact(question, value, 
               PSMethodUserSelected.getInstance(),
               PSMethodUserSelected.getInstance());
session.getBlackboard().addValueFact(fact);
}}}
/%
 
Please note, that we create a new {{Fact}} having the question and value. Additionally, the source of the fact is the User (PSMethodUserSelected) and the corresponding problem-solver is also the user.
In different scenarios, the source may be the instance of a {{Rule}} used in the context of a particular PSMethod instance.

!! Check the Derived Solutions

We retrieve the list of derived solutions together with their state by iterating over all solutions in the knowledge base and by asking for a diagnosis {{Rating}} that is different from UNCLEAR.
This way, we return solution instances with states ESTABLISHED, SUGGESTED, and EXCLUDED. 

%%prettify 
{{{
for (Solution solution : knowledgeBase.getSolutions()) {
    Rating state = session.getBlackboard().getState(solution);
    if (!state.hasState(Rating.State.UNCLEAR))
	out.println("  " + solution + " (" + state + ")");
}
}}}
/%


!! Revisit the entered Facts

You can simply retrieve all entered facts by the following code block:

%%prettify 
{{{
for (ProtocolEntry entry : session.getProtocol().getProtocolHistory()) {
    out.println(entry);
}
}}}
/%

Please note, that the session manages a {{Protocol}}, where entered findings (question/value tuples) are stored in a chronological order.
 


!! The Complete Example

__Note:__ The current version of the full example should be found in d3web-GlobalTests as the class {{de.d3web.demos.RunningACase}}.

%%prettify 
{{{
public void runDemoCase() throws IOException {
	KnowledgeBase knowledgeBase = buildKnowledgeBase();
	
	PrintStream out = System.out;
	// Create a case (problem-solving session and set all specified
	// question/answers
	out.println("+++ Setting values +++");
	Session session = SessionFactory.createSession(knowledgeBase);

	// set: pregnant = yes
	Fact fact1 = FactFactory.createFact(pregnant, yes, PSMethodUserSelected
				.getInstance(), PSMethodUserSelected.getInstance());
	session.getBlackboard().addValueFact(fact1);
	out.println(fact1);
	// set: weight = 80
	Fact fact2 = FactFactory.createFact(weight, new NumValue(80), 
			PSMethodUserSelected.getInstance(), 
			PSMethodUserSelected.getInstance());
	session.getBlackboard().addValueFact(fact2);
	out.println(fact2);
	
	// Print all solutions with a state != UNCLEAR
	out.println("+++ Solutions +++");
	for (Solution solution : knowledgeBase.getSolutions()) {
		Rating state = session.getBlackboard().getState(solution);
		if (!state.hasState(Rating.State.UNCLEAR))
			out.println("  " + solution + " (" + state + ")");
	}

	// Show all entered findings
	out.println("+++ Entered Questions +++");
	for (ProtocolEntry entry : session.getProtocol().getProtocolHistory()) {
		out.println("  " + entry);
	}
}


private KnowledgeBase buildKnowledgeBase() throws IOException {
	// root {container}
	// - demoQuestion {containers}
	// - pregnant [oc]
	// - weight [num]

	// Solution: dangerousMood
	InitPluginManager.init();
	KnowledgeBaseManagement kbm = KnowledgeBaseManagement.createInstance();
	QASet root = kbm.getKnowledgeBase().getRootQASet();

	demoQuestions = kbm.createQContainer("demoQuestions", root);
	pregnant = kbm.createQuestionOC("pregnant", demoQuestions, new String[] { "yes",
			"no" });
	yes = new ChoiceValue(kbm.findChoice(pregnant, "yes"));
	weight = kbm.createQuestionNum("weight", "weight", demoQuestions);

	dangerousMood = kbm.createSolution("dangerousMood");
	
	// Define the init questionnaire
	kbm.getKnowledgeBase().setInitQuestions(Arrays.asList(demoQuestions));
	
	// Define the magic rule: preganant=yes AND weight > 70 => dangerousMood (P7)
	List<Condition> terms = new ArrayList<Condition>();
	terms.add(new CondEqual(pregnant, yes));
	terms.add(new CondNumGreater(weight, Double.valueOf(70)));
	RuleFactory.createHeuristicPSRule("r1", dangerousMood, Score.P7, new CondAnd(terms));
	
	return kbm.getKnowledgeBase();
}
}}}
/%


%%tags 
howto create Session
%