1. Getting Started

1.1. Requirements

Jess is a programmer's library written in Java. Therefore, to use Jess, you'll need a Java Virtual Machine (JVM). You can get an excellent JVM for Windows, Linux, and Solaris free from Oracle's Java web site. Java for Mac OS/X is effectively built into the OS. Jess 8.0 is compatible with all released versions of Java starting with JDK 5 including Java 7, the latest release. Older Jess versions numbered 4.x were compatible with JDK 1.0, 5.x versions worked with JDK 1.1, Jess 6 worked with JDK 1.2, and Jess 7 required JDK 1.4.

Be sure your JVM is installed and working correctly before trying to use Jess.

To use the JessDE integrated development environment, you'll need version 3.7 or later of the Eclipse SDK from http://www.eclipse.org; in particular, you'll need a version that supports Java development with the Eclipse JDT. Be sure that Eclipse is installed and working properly before installing the JessDE.

The Jess library serves as an interpreter for another language, which I will refer to in this document as the Jess language. The Jess language is a highly specialized form of Lisp.

I am going to assume that you, the reader, are a programmer who will be using either one or both of these languages. I will assume that all readers have at least a minimal facility with Java. You must have a Java runtime system, and you must know how to use it at least in a simple way. You should know how to use it to

If you do not have at least this passing familiarity with a Java environment, then may I suggest you purchase an introductory book on the topic. A wealth of Java tutorials and documentation is available at no cost from the Oracle web site.

For those readers who are going to program in the Jess language, I assume general familiarity with the principles of programming. I will describe the entire Jess language, so no familiarity with Lisp is required (although some is helpful.) Furthermore, I will attempt to describe, to the extent possible, the important concepts of rule-based systems as they apply to Jess. Again, though, I will assume that the reader has some familiarity with these concepts and more. If you are unfamiliar with rule-based systems, you may want to purchase a text on this topic as well.

Many readers will want to extend Jess' capabilities by either adding commands (written in Java) to the Jess language, or embedding the Jess library in a Java application. Others will want to use the Jess language's Java integration capabilities to call Java functions from Jess language programs. In sections of this document targeted towards these readers, I will assume moderate knowledge of Java programming. I will not teach any aspects of the Java language. The interested reader is once again referred to your local bookstore.

This document contains a bibliography wherein a number of books on all these topics are listed.

1.2. Getting ready

1.2.1. Unpacking the Distribution

 Jess is supplied as a single .zip file which can be used on all supported platforms. This single file contains all you need to use Jess on Windows, UNIX, or the Mac (except for a JVM, which you must install yourself.)

When Jess is unpacked, you should have a directory named Jess80a1/. Inside this directory should be the following files and subdirectories:

README A quick start guide.
LICENSE Information about your rights regarding the use of Jess.
bin A directory containing a Windows batch file (jess.bat) and a UNIX shell script (jess) that you can use to start the Jess command prompt.
lib A directory containing Jess itself, as a Java archive file. Note that this is not a "clickable" archive file; you can't double-click on it to run Jess. This is deliberate. This directory also contains the JSR-94 (javax.rules) API in the file jsr94.jar.
docs/ This documentation. "index.html" is the entry point for the Jess manual.
examples/jess A directory of small example programs in the Jess language.
examples/xml A directory of small example programs in JessML, Jess's XML rule language.
eclipse The JessDE, Jess's Integrated Development Environment, supplied as a set of plugins for Eclipse 3.7 and up. See here for installation instructions.
src (Optional) If this directory is present, it contains the full source for the Jess rule engine and development environment, including an Ant script for building it.

1.2.2. Command-line Interface

 Jess has an interactive command-line interface. The distribution includes two scripts that you can run to get a Jess command prompt: one for Windows, and one for UNIX. They're both in the bin/ directory. Run the one that's appropriate for your system, and you should see something like this 
C:\Jess80a1> bin\jess.bat

Jess, the Rule Engine for the Java Platform
Copyright (C) 2013 Sandia Corporation
Jess Version 8.0a1 8/1/2013

Jess>
That's the Jess prompt. Try evaluating a prefix math expression like "(+ 2 2)". Don't forget those parentheses! 
Jess> (+ 2 2)
4
Jess evaluates this function, and prints the result. In the next chapter of this manual, we'll look at the syntax of the Jess rule language itself.

To execute a file of Jess code from the Jess prompt, use the batch command: 

Jess> (batch "examples/jess/sticks.clp")
Who moves first (Computer: c Human: h)?
Note that in the preceding example, you type what follows the Jess> prompt, and Jess responds with the text on the next line. I will follow this convention throughout this manual.

To execute the same Jess program directly from the operating-system prompt, you can pass the name of the program as an argument to the script that starts Jess: 
C:\Jess80a1> bin\jess.bat examples\jess\sticks.clp

Jess, the Rule Engine for the Java Platform
Copyright (C) 2013 Sandia Corporation
Jess Version 8.0a1 8/1/2013

Who moves first (Computer: c Human: h)?
1.2.2.1. Command-line editing

When working at the Jess command line, it's convenient to be able to edit and reinvoke previous commands. The Jess library doesn't support this directly, but the excellent open-source product JLine can add this capability to any command-line Java program, Jess included. JLine works great with the Jess prompt and I strongly recommend it.

1.2.2.2. Graphical console
 The class jess.awt.Console is a simple graphical version of the Jess command-line interface. You type into a text field at the bottom of the window, and output appears in a scrolling window above. Type 
C:\Jess80a1> java -classpath lib\jess.jar jess.awt.Console
from the Jess80a1 directory to try it.

1.2.3. Java Programming with Jess

 To use Jess as a library from your Java programs, the file jess.jar (in the lib directory) must either be on your class path, be installed as a standard extension, or your development tools must be set up to recognize it. The details of doing these tasks are system and environment dependent, but setting the class path usually involves modifying an environment variable, and installing a standard extension simply means copying jess.jar into your $(JAVA_HOME)/jre/lib/ext directory. Refer to the Java documentation or an introductory Java text for details.

1.2.4. Jess Example Programs

 There are some simple example programs (in the examples/jess and examples/xml directories) that you can use to test that you have installed Jess properly. These include fullmab.clp, zebra.clp, and wordgame.clp. fullmab.clp is a version of the classic Monkey and Bananas problem. To run it yourself from the command line, just type: 
C:\Jess80a1> bin\jess examples\jess\fullmab.clp
and the problem should run, producing a few screens of output. Any file of Jess code can be run this way. Giving Jess a file name on the command line is like using the batch function. Therefore, you generally need to make sure that the file ends with: 
Jess> (reset)
(run)
or no rules will fire. The zebra.clp and wordgame.clp programs are two classic examples selected to show how Jess deals with tough situations. These examples both generate large numbers of partial pattern matches, so they are slow and use up a lot of memory. Other examples include sticks.clp (an interactive game) and jframe.clp (a demo of building a graphical interface using Jess's Java integration capabilities).

The XML examples are in individual subdirectories; each subdirectory contains a README file with instructions for running that example.