Querying a knowledge model

Note Before you begin working through this article, please ensure you have: Installed the following software on your machine: Erudine Behaviour Engine 2.4. Eclipse Latest Release - http://download.eclipse.org/eclipse/downloads/ Sun Java SE5.0 SDK Latest Release - http://java.sun.com/javase/downloads/index_jdk5.jsp. Created a new Eclipse Java Project using the Create project from existing source wizard and the training project shipped with the Erudine Behaviour Engine and located in C:\Program Files\Erudine\Training\Development\Training

Purpose

To query the structure of a knowledge model programmatically.

Prerequisites

In order to complete this exercise, it is necessary to have worked through the Starting the Erudine Behaviour Engine exercise so that it is possible to deploy a knowledge model for querying. If it is not possible to work through the exercise, the completed version of the exercise can be found in the C:\Program Files\Erudine\Training\Development\TrainingComplete folder.

Theory

In this exercise, you will learn how to use a Behaviour Execution Engine to interface with a knowledge model programmatically. Once an instance of a knowledge model is obtained, you will be able to query its data flow model and examine knowledge nodes within the knowledge model. The data flow model will allow you not only to determine which nodes are in the model, but also to investigate the relationships between them. This exercise will use a simple knowledge model that compares a given number with five and classifies it as either 'greater', 'lesser' or 'equal'. Methods will be created to determine whether a knowledge model contains a knowledge node with a given name and to retrieve the children or parents of a given knowledge node.

Actions

Examining the existing knowledge model

To view the structure of the knowledge nodes within the existing knowledge model:

1. Start the Behaviour Authoring Environment.
2. Open the CompareNumberWithFive knowledge model.
   This knowledge model is located in the Training/resources folder of your Eclipse workspace. If, for example, your workspace was C:\Program Files\Erudine\Training\Development , then the knowledge model could be found at C:\Program Files\Erudine\Training\Development\resources\CompareNumberWithFive.knm .
3. Examine the knowledge nodes contained within the knowledge model and the links between them.
   You will create methods that allow you to examine the knowledge model's knowledge nodes programmatically.
4. Close the Behaviour Authoring Environment.

Writing code to query a knowledge model

To create code that queries a knowledge model:

1. Open Eclipse.
2. Expand the src/java folder.
3. Expand the exercise.queryingKnm package.
4. Open the CompareNumberWithFiveQueryTool class.
   This class contains some pre-completed methods so that this exercise can focus on the steps involved in querying the knowledge model.
   The constructor CompareNumberWithFiveQueryTool uses the StartEbeCommand class to create an instance of the Behaviour Execution Engine and deploy the CompareNumberWithFive knowledge model. In this exercise, it is the structure of this knowledge model that will be queried.
5. Delete the following lines from the doesNodeExist, getChildNodeNames and getParentNodeNames methods of the CompareNumberWithFiveQueryTool class:

   // TODO - Remove the line below when starting this exercise
   return null;

   These lines were included in the supplied code to avoid compiler errors.

6. Collapse the src/java folder and expand the resources folder.
7. Open the CompareNumberWithFiveQueryTool_DoesNodeExist.java file.
8. Copy the following text from the file into the doesNodeExist method of the CompareNumberWithFiveQueryTool class:

   IDataFlowModel dataFlowModel = knowledgeModel.getDataFlowModel();
   return dataFlowModel.contains( nodeName );

   The first line queries the knowledge model and retrieves a programmatic interface to its data flow model. The data flow model stores the knowledge model's structure and it is possible to query it to determine the relationships between knowledge nodes. In the second line of the method, we query the data flow model to determine if a knowledge node with the given name exists in the knowledge model.

9. Open the CompareNumberWithFiveQueryTool_GetChildNodeNames.java file.
10. Copy the following text from the file into the getChildNodeNames method of the CompareNumberWithFiveQueryTool class:

    IDataFlowModel dataFlowModel = knowledgeModel.getDataFlowModel();
    return dataFlowModel.getChildNodes( nodeName );

    In the first line, we retrieve the data flow model as above. In the second line of the method, the child nodes are obtained from the data flow model and returned.
    The IDataFlowModel interface provides a number of methods that allow its users to query the structure of a knowledge model. For example, it is possible to obtain a list of all the knowledge nodes in the knowledge model. You may wish to experiment with the different methods available.

11. Open the CompareNumberWithFiveQueryTool_GetParentNodeNames.java file.
12. Copy the following text from the file into the getParentNodeNames method of the CompareNumberWithFiveQueryTool class:

    IDataFlowModel dataFlowModel = knowledgeModel.getDataFlowModel();
    return dataFlowModel.getParentNodes( nodeName );

    This method works in exactly the same way as the getChildNodeNames method, but returns the given nodes parents rather than children.
    

13. Press Ctrl + Shift + O to organise the imports.

Testing the code that queries a knowledge model

Once the code has been created, it is necessary to test it. The most obvious way to test the code is to compare the results achieved from using your class with those you would expect by examining the knowledge model through the toolkit. This process can be mechanised using JUnit tests.
To test the code that queries a knowledge model:

1. Collapse the resources folder and expand the src/unit folder.
2. Expand the exercise.queryingKnm package.
3. Open the CompareNumberWithFiveQueryToolTest class to display its contents.
4. Right click over the Java code and select Run As > JUnit Test from the context menu.
   This runs the tests contained in CompareNumberWithFiveQueryToolTest class against the CompareNumberWithFiveQueryTool class that has been created in this exercise.
   If the tests are successful, confirming that your function has been correctly implemented, the JUnit bar in the top left of the screen will go green.
5. Examine the testDoesNodeExist method.
   This method tests that the doesNodeExist method returns the same values that are expected when interrogating the knowledge model through the Behaviour Authoring Environment. The test checks that the method finds all of the knowledge nodes in the knowledge model correctly. It also checks that it does not find knowledge nodes with names not in the knowledge model. This includes knowledge nodes whose name differs only by case and knowledge node with a zero-length name.
6. Examine the testGetChildNodeNames method.
   This method tests that the getChildNodeNames method returns the same values that are expected when interrogating the knowledge model through the Behaviour Authoring Environment. The test checks that the method finds all of the children of all of the knowledge nodes in the knowledge model correctly. Including those knowledge nodes with zero, one or many children. It also checks that when a name is provided that does not correspond to a knowledge node within the knowledge model, null is returned.
7. Examine the testGetParentNodeNames method.
   This method tests that the getParentNodeNames method returns the same values that are expected when interrogating the knowledge model through the Behaviour Authoring Environment. The test checks that the method finds all of the parents of all of the knowledge nodes in the knowledge model correctly. This includes those knowledge nodes with zero or one parents. It also checks that when a name is provided that does not correspond to a knowledge node within the knowledge model, null is returned.
8. Close Eclipse.

Platform: all
EBE Version: 2.4
Category: Development Training Guide
Author: Patrick Peisker