AliceServlet Readme v. 1.10

What is AliceServlet?

AliceServlet.java is a Java Servlet interface for the ALICE chatterbot program. It enables you to run ALICE as a servlet from any servlet enabled web server.

What do I need to run it?

To use AliceServlet, you must first have an installation of the ALICE package. This is available at http://www.alicebot.org. Also, as with any servlet, to compile or run this program, you must have the Java Servlet Development Kit (JSDK.) This can be downloaded at http://java.sun.com. Lastly, you need a web server configured to run Java servlets.

If the server your want to run your servlets on is not yours and you are using your ISPs web server, you will need some basic information from your ISP about your account. They should have information available about how they have set your account up to use your servlets. Your ISP will specify one directory for you to put your servlets in. You will need to know where this is. There is also a "zone" properties file associated with your servlet directory. If your ISP does not let you edit this yourself, you will need to ask them to add one line to your servlet zone property file. (A simple process.)

How do I install and set up the servlet?

Here is a step by step setup procedure to help you get your AliceServlet running. Please note that although this guide will help you get your servlet set up, the ALICE package documentation should also be consulted to help you configure the ALICE chat bot. Also, the steps are geared towards setting up your servlet to run with Apache’s Jserv, a popular servlet server. However, the general steps will apply to any server setup. Do not be intimidated by the many steps, it’s actually a simple process, I just want to be complete. ;)

Step-by-step:

  1. Copy the AliceServlet.class file into the directory in which you have installed the ALICE package. (This is found in the "servlet" subdirectory in the ALICE installation, or it can be downloaded at "http://www.geocities.com/krisdrent" in the AliceServlet package.)
  2. If you haven’t already, move the ALICE directory into your specified servlet directory (e.g. "/home/kdrent/servlets/alicebot").
  3. If you want to move your AIML files or log files to individual directories to group them together for easier administration, do so now. Otherwise you can leave them in the main ALICE directory. (I have subdirectories called "aiml", "logs", etc… to help organize my setup. But this is not necessary. You just need to know the path of where they all reside.)
  4. Edit the globals.txt file in the ALICE directory. There a couple entries that specify where files are located, you need to edit these to point to your files with FULL PATHS given. This is important. If you did not move any of your aiml or other data files, then these paths will be to your ALICE directory. If you moved any files, simply make sure that these paths point to those files. Here is an example from my setup:

    5.  
        BotFile=/home/kdrent/servlets/alice/aiml/B.aiml
        LogFile=/home/kdrent/servlets/alice/dialog.txt
        AnalysisFile=/home/kdrent/servlets/alice/dialog.txt
     
  5. The servlet requires one parameter. Parameters for servlets are specified in a properties file associated with your servlet directory. This file is loaded by the servlet server so it will know how to run your servlet. If you do not know where this file is or do not have access to it, you will need to ask your system administrator or ISP where to find it or ask them to add the parameter to your properties file. (Simply tell them you need to add a parameter to your "servlet zone properties" file for your servlet.) The name of the parameter is "datadir" and its value should be the path of your ALICE directory.

    6.  
    For example, in an Apache JServ setup, the format for adding a parameter for a servlet is:
        servlet.[classname].initArgs=[argname]=[argvalue]
    So in my servlet zone properties file I would add the line:
        servlet.AliceServlet.initArgs=datadir=/home/kdrent/servlets/alice

    (NOTE: in this file, you can also provide other information about the servlet, such as aliases, and whether your servlet should be loaded as soon as the web server is started, etc… However, these setup issues are beyond the scope or purpose of this AliceServlet document. See your servlet server’s documentation for more information about this.)

    [Apache Jakarta-Tomcat users: the file you will edit will be the "WEB-INF/web.xml" file associated with your jsp/servlet "application" space. Use the <init-param> tag. See tomcat documentation on usage.]
     

  6. Give it a try! Point your web browser to your servlet. (Ex. http://www.mydomain.com/servlet/AliceServlet or http://www.myISPdomain.com/~myname/servlet/AliceServlet ) The server should then load the servlet which will send back a simple input form for you to begin your conversation.
NOTE: if this is your first time accessing the servlet, then the server will just now be loading ALICE. It will take a minute or so for ALICE to load the AIML files into her brain. Until she does that, she may not seem to respond very intelligently. This loading process will only happen once (once every time the server is started.) If you have any trouble, please check your server specific setup requirements. If you find any problems with the steps listed here, e-mail me at "drent@sirkus.unl.edu".

How do I customize the output?

There are two options you can choose from to define the output of the servlet:

  1. "full"
  2. "template"
These are options that you set in a parameter called "format" in your HTML form that refers to the servlet on your server. ("srvhome.html" is a sample starting HTML file for AliceServlet.)

Choosing the "full" option gives the fully automated version. ("srvhome.html" uses this by default.) Using this, the response pages from AliceServlet will be generated by the program in a default format. This means you don’t have to create any other pages other than your start page. Everything from there on out will be automatically generated for you.

The other option, "template", allows you to customize what the output from the servlet will look like. On start-up, AliceServlet reads in two files: "srvheader.html" and "srvtrailer.html". These two files are then used in every response that ALICE gives to an input request. The servlet takes the users input statement then forms the robot response, and then sends back [srvhheader.html] [robot text response] [srvtrailer.html]. This means that whatever html you create in srvheader.html and srvtrailer.html will be output with each response, with the robot’s response sandwiched between them. Note that there are srvheader.html and srvtrailer.html files included in AliceServlet.zip (or servlet directory in the ALICE package) to use as a reference.

Please note that if you use the "template" option, you do not include the HTML form in the HTML files. The input form is included in the robot response. If you need to customize the form, you can do so by editing the Java source code to the servlet (AliceServlet.java). The code is well commented and straightforward. But for most applications, the default HTML form should work perfectly.

What is the "response" format?

There is actually a third format option in addition to those listed above: "response". This option tells the servlet to only return the response text from the robot without any HTML or formatting. This can be useful in specialized scenarios with dynamic HTML sites, but otherwise is of little interest to most users.

What is ServletServer.class?

ServletServer is a class file that you can run to test AliceServlet. It is just like the servlet server that comes with the JSDK. It uses port 8080 by default, and the default servlet directory it uses is the directory you run ServletServer from, which should be your ALICE install directory. The ServletServer is useful for testing and debugging your HTML templates or servlet implementation locally when your developing on a machine that does not have a web server running with servlet capabilities.

Default HTML files note:

The HTML files in this package (srvhome.html, srvheader.html, and srvtrailer.html) are included to get you started with your templates. By default, there are images and applets referenced in these files that load from alicebot.org. I recommend changing these to load from your own site for performance reasons. Alicebot.org can get heavy traffic and this could cause the loading of your HTML pages in your browser to slow down significantly during those high traffic times. If you use the copies of the images and applets from your own site the alicebot.org traffic will not affect you.

Where Can I Find More Information About ALICE?

The ALICE project is an open source effort originally designed by Dr. Richard Wallace. Many other developers have volunteered time and skill to help develop ALICE. If you would like to visit Dr. Wallace’s web site for ALICE, it can be fount at http://www.alicebot.org. You can also visit The ALICE Connection web site which also contains development and implementation documentation as well as source code, http://www.geocities.com/krisdrent.

If you find bugs in AliceServlet please send them to me, Kris Drent, drent@sirkus.unl.edu

AliceServlet is currently maintained at:
The ALICE Connection: http://www.geocities.com/krisdrent

For information on ALICE and to download, see the above, or visit ALICE’s home:
The ALICE NEXUS: http://www.alicebot.org