Servlet Interface

Java Servlet Interface

Requirements

The Java Servlet interface conforms to version 2.3 of the Servlet Specification and will run under any web server that supports that Servlet interface.

Running Under Tomcat

The Java Servlet web server interface is located in the runtime/servlet subdirectory. Under Unix, Tomcat generally installs in a directory named jakarta-tomcat-X.X. Under Windows, the directory is called 'Apache Tomcat X.X. The examples below use the Windows naming. If you are running under Unix, make the appropriate substitutions.

In order to run this servlet under Tomcat (where X.X is replaced by the version of Tomcat you are running, and N.N by the version of Java you are running):

Create a sudirectory in ...Apache Tomcat X.X\webapps named 'amzi'.
Copy the knowledgewright4\runtime\servlet\WEB-INF subdirectory tree to ...Apache Tomcat X.X\webapps\amzi so now you have ...Apache Tomcat X.X\webapps\amzi\WEB-INF...
Copy amzi.dll, amzijni.dll, amzi.cfg, aosutils.lsx and aodbc.lsx (Windows only) from knowledgewright4\workshop to ...Apache Tomcat X.X\webapps\amzi\WEB-INF\classes
Copy a jig, either basic.xpl or support.xpl, from knowledgewright4\workshop\jigs to ..Apache Tomcat X.X\webapps\amzi.
Copy your knowledgebase to ..Apache Tomcat X.X\webapps\amzi modified as described in the following section.
Add ...Apache Tomcat X.X\webapps\amzi\WEB-INF\classes to your PATH environment variable.
Stop and restart Tomcat

Question_Top and Output_Continue

In your main knowledgebase object, you must have these minimal HTML elements which are inserted above and below all questions asked of the user:

Property Name	Minimal Value
question_top	<HTML> <HEAD></HEAD> <BODY> <FORM METHOD="GET" ACTION= "%system(form_url)%">
question_bottom	<INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM> </BODY> </HTML>
output_continue (not in all Jigs)	<FORM METHOD="GET" ACTION= "%system(form_url)%"> <INPUT NAME="Submit" TYPE="Submit" VALUE="Continue"> </INPUT> </FORM>

The %system(form_url)% will be replaced at runtime with the rewritten URL for the servlet. This URL is generated by most servlet containers to preserve the session id when cookies are not available or are not used. You can hard-code your program name instead if you do not need this feature (e.g. /amzi/KW). The program name used in question_bottom and output_continue must be the same and must match the servlet URL.

In addition, some jigs (notably Basic) also have an output_continue property in the knowledgebase object. This is used when there is output for the user and the reasoning process is not complete. That is, some intermediate results or information are being displayed for the user. In this case the output_continue contents are added to the web page and are an empty HTML form that continues the reasoning process.

In addition the following properties are passed to your web server:

Parameter	Description	Examples
charset	The character set used in your knowledgebase	ISO-8859-1 big5

Running in Your Web Browser

To run your knowledgebase, type into your browser one of the following URLs:

Unix: http://127.0.0.1:8080/amzi/KW?kb_file=hello.kb
Windows: http://localhost:8080/amzi/KW?kb_file=hello.kb

Replace the 127.0.0.1 or 'localhost' with the name (www.company.com) or IP address of the server you have installed the KnowledgeWright servlet on.

Starting with Your Own HTML Form

Some applications may want to start the reasoning process by having the user answer a fixed set of questions at the outset. To do this you create an HTML file with an HTML form in it. The form elements must have names and values that match question objects in your knowledgebase. The 'submit' button is set to invoke KW (e.g. /amzi/KW). You must specify a kb_file by creating a hidden input named kb_file with a value that is the name of your knowledgebase. You can also have hidden inputs for directory, temp_directory and log_file (see below).

Servlet Parameters

There are additional parameters that you can specify in the query string. Separate each of the parameters by ampersands (&) and encode them with standard URL encoding. The full set of parameters are:

Parameter	Description	Examples
kb_file	The name of the knowledgebase file (no quotes)	amzi_website_advisor.kb
directory	The directory where the kb_file is located.	c:\Tomcat\webapps\amzi /usr/local/tomcat/webapps/amzi
temp_directory	The directory where the temporary session files are created as well as log files (if you have specified one) and any other temporary files needed by KnowledgeWright. Note Java Servlets must have write access to this directory.	c:\Tomcat\temp /usr/local/tomcat/temp
log_file	The name of the log file that details the execution. It will have the same contents as the log in the KnowledgeWright Workshop.	kwrun.log
html_file	If you would like to start your knowledgebase with an HTML form for the user to input some answers to questions in your knowledgebase, then use this option to specify the HTML file containing the form. Make sure you have a hidden facts for any of the above parameters. (See above.)	myform.html

Debugging Servlet Problems

The first thing to do when you encounter a problem is to specify a log_file in the query string where you invoke the servlet.

To specify your kb file and a log file:

Unix: http://127.0.0.1:8080/amzi/KW?kb_file=hello.kb&log_file=kwrun.log
Windows: http://localhost:8080/amzi/KW?kb_file=hello.kb&log_file=kwrun.log

This will create a log file in the same directory as your knowledgebase file. Study its contents, especially at the bottom to see if the problem is explained.

Open an Amzi! Logic Server Trace File for Amzi! Tech Support

If that does not make the problem clear, the next step is to specify a log file in Amzi! Prolog + Logic Server. To do this, add the following lines to your amzi.cfg file in the WEB-INF/classes directory:

apitrace = on 
logfile = c:\amziapi.log

If you need technical support, please e-mail the browser output when you run KW, your KnowledgeWright log file and Amzi! Logic Server trace file along with your knowledgebase to tech support.

Modifying the Java Servlet (Full Version)

To modify and rebuild the servlet you can use the JBuilder project, servlet_run.jpx. Alternatively:

Set JAVA_HOME=c:\jdkN.N
Set the CLASSPATH to include knowledgewright4/runtime/servlet/WEB-INF/classes and servlet.jar. For Tomcat, servlet.jar is found in jakarta-tomcat-X.X\common\lib.
Compile the java source files with javac.
Copy the class files to the WEB-INF/classes directory as described at the beginning of this section.

References

See the Java Tutorial to learn How to Write Servlets.

To learn about configuring servlets under Tomcat, see the Java Tutorial Lesson on Running Servlets.

For information on how to install and run Tomcat under IIS and Windows see How To Setup TOMCAT 4.0.1 on Windows 2000 with IIS and NT Service