<tags>HowTo</tags>
[{TableOfContents }]

!!! How to write a SubtreeHandler


Create a class extending the abstract class SubtreeHandler.\\

SubtreeHandler has only one abstract methods. The non-abstract methods are described further down.

%%prettify 
{{{
public abstract Collection<KDOMReportMessage> create(KnowWEArticle article, Section s);
}}}
/%


The Section is a section of the type the handler is registered for, the KnowWEArticle is the article that called this method with this specific Section. Note that this article can be another article than the article that is returned by calling the getArticle()-method of the Section, becaus Sections can also be included. If, for example, a Section from article A is included by article B and article B is currently revising the KDOM and executes this handler with this section, the attribute KnowWEArticle given in this method will point to article B, while the getArticle()-method of the Section still points to article A.\\
The returned Collection of KDOMReportMessages needs to contain the Messages produced by the [SubtreeHandler|https://isci.informatik.uni-wuerzburg.de/javadoc/KnowWE/de/knowwe/core/kdom/subtreeHandler/SubtreeHandler.html] (read more about it in the chapter about Messages further below). 

!!How to register a SubtreeHandler using Priorities
If you have created your own SubtreeHandler and want to register the handler to a type, call the addSubtreeHandler-method (inherited from AbstractKnowWEObjectType) of the type object you want to attach the handler to:

%%prettify 
{{{
public void addSubtreeHandler([Priority p,] SubtreeHandler handler);
}}}
/%

The attribute Priority in this method is optional. If you don't specify a priority, the handler will be added with default priority.

!Order of execution of SubtreeHandlers:

After the KDOM of an article is completed, for all Sections whos KnowWEObjectType has SubtreeHandlers registered to it, the method create(...) will be executed for all these SubtreeHandlers. The order of execution of the handlers is very specific and it works like this: At first, a list of all Sections of the KDOM is retrieved from the article in post-order. So the children of a Section are ordered prior to the Section itself. Children of the same Section appear in this list in the same order as they appear in the text of the article.\\
After having this list of Sections, another map is created. The map contains lists with Sections whos KnowWEObjectType have SubtreeHandlers with a certain priority registered to them. These lists are hashed after this priority and the map is sorted in a descending order (of priorities). Inside the single lists with all Sections with handlers of a certain priority, the Sections appear in the same order as they appear in the original list with all Sections in post-order. Sections can appear multiple times or not at all in this map: If their KnowWEObjectType has multiple SubtreeHandlers with different priorities, the same Section will appear in every list of each different priority of its handlers. If the KnowWEObjectType has no SubtreeHandler, it simply will no appear in any list in the map.\\
\\
__Example:__\\
Given is the following simplified KDOM. Each node represents a Section with a certain KnowWEObjectType denoted underlined in the top. The SubtreeHandlers registered to the KnowWEObjectTypes are denoted below, together with the Priority they were registered with.
[{Image src='handlerpriority.png' align='left'}]\\
Let's take a look at the list of all Sections retrieved in post-order:
{{{
QuestionsSection, XCList, XCList, Include, RulesSection, SolutionsSection, KnowWEArticle
}}}
With this list, the map of lists sorted after priorites is created:
{{{
Priority.HIGHEST: SolutionsSection
Priority.HIGHER: QuestionsSection
Priority.DEFAULT: QuestionsSection, XCList, XCList, RulesSection
}}}
This map now pretty much represents the order the SubtreeHandlers are executed in. KnowWE will simply iterate in descending priority-order over the lists of the map and executes all SubtreeHandlers of the priority of the list that is currently iterated. If the KnowWEObjectType of the Section also contains handlers with a different priority, these handlers will not be executed until the list with the corresponding priority is iterated.


!!How to use Messages in a SubtreeHandler

If you use messages in a SubtreeHandler, consider that the method create(...) of the SubtreeHandlers can be executed multiple times for the same Section object (because of the incremental update). Therefore, the Collection of messages stored by the SubtreeHandler needs to always represent the current state of this Handler, including the case that no messages are produced at all. In this case, return or store an empty Collection (to overwrite possible error messages created in a previous execution of the handler with the same Section object).
If you want the messages to be preserved, for example in case the execution of the handler gets aborted due to the incremental update, return null like before.\\ 
\\
__Hint:__ Use Arrays.asList((KDOMReportMessage) yourMessage) to create a Collection if you just have a single message.
\\
\\
Different types of messages can be used in SubtreeHandlers. However the recommented type is the KDOMReportMessage, since it is supported in the type of the Collection returned by the create method. Basically, returning a Collection of messages in the handler equals the storage of a Collection of messages using the storeMessages() methods provided by KnowWEUtils. Using KDOMReportMessages and returning them instead of storing other types makes it just easier, because you have to care less about correct usage and the correct attributes required by the methods from KnowWEUtils. It's also shorter code ;-) .
Of course all of this only applies if you actually use messages in your handler. If you don't, you can just return null everywhere. Simple rule: As soon as you return or store messages at one of the possible outcomes (returns) of the create method, you have to do it on every. 
\\

!KDOMReportMessages in SubtreeHandlers

To understand how KDOMReportMessages should and should not be used in SubtreeHandlers, take a look at the following examples. Note, that KDOMNotice, KDOMWarning and KDOMError are abstract classes. In the examples they are used only to show the idea of which subclass of the KDOMReportMessage should be used in which situation. If you actually implement your handler, you again need subclasses of these three subclasses. A variety of them can by found in de.d3web.we.kdom.report.message in the KnowWE-core project.
\\
\\
__Examples:__\\
Right:
%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    doThat();
    if (a) {
        return Arrays.asList((KDOMReportMessage) new KDOMNotice("Object created");
    } else {
        return Arrays.asList((KDOMReportMessage) new KDOMError("Object NOT created");
    }
}
}}}
/%
Also right:
%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    List<KDOMReportMessage> msgs = new ArrayList<KDOMReportMessage>();
    if (a && b) {
        msgs.add(new KDOMNotice("Object created");
        msgs.add(new KDOMWarning("Minor syntax error");
    } else {
        msgs.add(new KDOMError("Object NOT created");
    }
    doThat();
    return msgs;
}
}}}
/%
Wrong:
%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    if (b) {
        return Arrays.asList((KDOMReportMessage) new KDOMError("Object NOT created");
    }
    doThat();
    // everything is ok, so there is no need for a Message?!
    return null;
}
}}}
/%
\\
In the last (wrong) example the programmer thinks, that he can return null, because he decided to only use messages if something bad happens. But that is exactly wrong. Of course he can decide to just use messages if something bad happens, but then he needs to return an empty list instead of null. Otherwise, if the Section was reused and had an error in the last version (e.g. Question not found) but no error in the current version (Question was added by another Section), then this no longer valid error message would not be overwritten.
\\
\\
Corrected the wrong example:

%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    if (b) {
        return Arrays.asList((KDOMReportMessage) new KDOMError("Object NOT created");
    }
    doThat();
    // everything is ok, so there is no need for a Message?!
    return new ArrayList<KDOMReportMessage>(0);
}
}}}
/%
\\
Valid example for usage in incremental handlers:

%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {

    if (getKBM() == null)
        return null;
        
    doThis();
    doThat();
    if (a) {
        return Arrays.asList((KDOMReportMessage) new KDOMNotice("Object created");
    } else {
        return Arrays.asList((KDOMReportMessage) new KDOMError("Object NOT created");
    }
}
}}}
/%
\\
Note, that we return null in the case that getKBM equals null. We do that, because we actually want to preserve the last collection of messages. The method getKBM (read more about it in the chapter about KnowledgeBaseManagement further below) only returns null, if this reused Sections doesn't need to be revised again, because there are no changes in the article, that could alter the outcome or the messages produced by this SubtreeHandler with this Section in relation to the last version of the article. So there is no need to do more and the messages from the last version are still correct.


!d3web.report.Messages in SubtreeHandlers

Because the type of the Collection returned by create is KDOMReportMessage, it is highly recommended to use only that type inside the SubtreeHandlers. Use the d3web.report.Message only if they, for example, are returned by a d3web builder. Note that you cannot use that message type in the returned Collection, therefore you have to store them manually with AbstractKnowWEObjectType#storeMessages(KnowWEArticle, Section, Class, Collection<Message>) and return null instead. The methods to store messages in the AbstractKnowWEObjectType are simply using the corresponding methods from KnowWEUtils with the message type already preselected, to make usage a little bit easier. Check out the Javadocs for right use of the remaining attributes and also be aware, that you can use all methods to store Messages only once for each set of attributes (KnowWEArticle, Section, Class of source). If you use the method a second time with the same attributes, the first Collection gets overwritten.
\\
\\
__Examples:__
Right:
%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    doThat();
    if (a) {
        AbstractKnowWEObjectType.storeSingleMessage(article, s, this.getClass(), new Message("Object created"));
        return null;
    } else {
        AbstractKnowWEObjectType.storeSingleMessage(article, s, this.getClass(), new Message("Object NOT created"));
        return null;
    }
}
}}}
/%
You can already see, it's less elegant.\\
Note, that the there is a special method for storing just one Message. But be aware, that you also can use this method only once for each KnowWEArticle, Section and Class of the source. So if you want to store more than one message for one outcome of the create method, you have to use Collections.
\\
\\
Wrong:
%%prettify 
{{{
public Collection<KDOMReportMessage> create(KnowWEArticle article, Section s) {
    doThis();
    if (b) {
        AbstractKnowWEObjectType.storeSingleMessage(article, s, this.getClass(), new Message("Object NOT created"));
        return;
    }
    doThat();
    // everything is ok, so there is no need for a Message?!
    return null;
}
}}}
/%
The problem is basically the same as in the wrong example for KDOMReportMessages. At the first return a Message is stored, at the second, nothing is done. So if the handler is executed a second time and b == false while it was true the first time, the old Message doesn't get overwritten.

!Other message types in SubtreeHandlers

Because the type of the Collection returned by create is KDOMReportMessage, it is highly recommended to use only that type inside the SubtreeHandlers. But if you want to use your own type of messages, because somehow the already given types don't match your requirements, you can of course do that. To store them, the same rules apply as for the other message types. However you probably have to directly use the methods of KnowWEUtils to store them:

%%prettify 
{{{
public static void storeMessages(KnowWEArticle article, Section<?> sec,
			Class<?> source, Class<MSGType> msgType, Collection<MSGType> msgs);
}}}
/%
Parameters:\\
First is the article you are storing the message for. That is not necessarily the same as the one you get calling Section#getArticle(), because Sections can also be included.
Second is the Section you are storing the message for. Third the Class of the source of the message. Fourth you need the class of the message type you want to store, fifth is the Collection of messages of this type.

!!How to use d3web in a SubtreeHandler

If you want to use d3web, respectively a KnowledgeBase in a SubtreeHandler, you have to extend the abstract D3webSubtreeHandler in the KnowWE-Plugin-d3web. It provides the method D3webSubtreeHandler#getKBM(KnowWEArticle).
\\
\\
__Example__ (implementing a D3webSubtreeHandler for the KnowWEObjectType QuestionDef)__:__
%%prettify 
{{{
public class CreateQuestionHandler extends QuestionTreeElementDefSubtreeHandler<QuestionDef> {
        
    @Override
    public Collection<KDOMReportMessage> create(KnowWEArticle article, Section<QuestionDef> sec) {
    
        ...
        
        KnowledgeBaseManagement mgn = getKBM(article);
        
        mgn.createQuestionYN(sec.getOriginalText(), D3webUtils.findParent(sec, mgn));
        
        ...
    }
}   
}}}
/%
\\
\\
In earlier versions of KnowWE, getKBM(KnowWEArticle) could return null under certain circumstances (connected with incremental updating). This doesn't happen anymore, so you don't have to worry about that :-) .

__Attention:__
The use of
%%prettify 
{{{
D3webModule.getKnowledgeRepresentationHandler(article.getWeb()).getKBM(article.getTitle());
}}}
/%
to retrieve the KnowledgeBaseManagement in a SubtreeHandler is now deprecated! Using this you can avoid extending the D3webSubtreeHandler which is not recommented, since extending the D3webSubtreeHandler also assure the correct handling of the KnowledgeBase in an incremental context.

!! How to implement incremental SubtreeHandlers

Currently (summer 2010), incremental updating is under constant development, so things might change frequently. I will however try to point out some of the basics for implementing an incrementally working SubtreeHandler for KnowWE.

The abstract class SubtreeHandler provides two important methods:

* create(...)

* destroy(...)

If KnowWE builds an article for the first time or a full parse is performed, the method create(...) will create for every Section everything there is to create, for example a Question that is added to the KnowledgeBase.
If the article then is edited and the text of this Section, respectively this Question changes, the method destroy(...) is called for the last version of this Section or Question to destroy exactly this outdated version of the Question in the KnowledgeBase. The new, changed version of the Section or Question then will again call create(...) to replace the previousely removed Question with the new version.
Sections that haven't changed and are both in the last and the current version of the KDOM can now be skipped from creating and destroying, which saves a lot of time and is the reason for incremental updating in the first place.
\\
\\



To determine whether the currently revised Section needs to be created, respectively destroyed or if it just can be skipped, ConstraintModules are registered to the SubtreeHandler. They decide whether create(...), respectively destroy(...) needs to be called for the current Section.\\
The abstract class SubtreeHandler already has some ConstraintModules that provide the basic logic, so that create(...) and destroy(...) will be executed for all Sections that have changed themselves, changed their position in the KDOM or if currently simply an full parse is performed. For more advanced SubtreeHandlers it might however be necessary to register additional ConstraintModules to further specifiy, when to create and destroy and when not to. The ConstraintModules registered to the abstract SubtreeHandler are well commentated and might serve as an example, if you need to implement ConstraintModules yourself.
\\

\\
!SubtreeHandlers preventing incremental update

If you get the following message while running KnowWE and editing articles, it means, that the currently edited article uses a KnowWEObjectTypes that, on the one hand, doesn't implement the necessary destroy method to work incrementally, but on the other hand uses an component like d3web in the create method. 

__Example:__
{{{
INFO: The following SubtreeHandlers prevent inrememental updating:
[SolutionsSubTreeHandler, QuestionsSectionSubTreeHandler]
}}}

If there are handlers using certain components like d3web, but are not made for incremental updating, the incremental update needs to be aborted and replaced by a full parse of the article.\\
This full parse is achieved by calling setFullParse(true) on the article currently revising the Section in the destroy method of the SubtreeHandler. For d3web this is the default, as long as nobody overrides the destroy method of the D3webSubtreeHandler.
\\
\\

Don't hesitate to contact me directly if you have additional questions, problems or ideas regarding SubtreeHandlers: albrecht.striffler<at>gmx.de
%%tags
howto
%