Java Class

• A Java Class Package the encapsulates a Logic Server Engine
• Methods that correspond to the Logic Server API Functions
• Use of Java's exception handling for API errors, and
• Java-like method interfaces.

The Java Logic Server methods are documented in the LSAPI Reference.

In addition, you can extend the Java Class to allow Prolog to call methods in your Java code.

The sections of this document are:

• Where to Learn About Java - Where to get Java software, tutorials and information.
• Installation - How to install the Logic Server as a Java class.
• Hello Prolog- Getting the Hello Prolog application up and running from Java.
• Overview - Conceptual overview of the Java version of the Logic Server.
• Using the Java Class - How to use the Logic Server from Java.
• Implementing Extended Predicates - How to add Prolog extended predicates written in Java.
• Converting Prolog Lists to Java Types - Some sample methods that make it easier to work with Prolog lists.
• Examples

Where to Learn About Java

Installation

To use the Java Class, you must make these files accessible to the calling environment:

• Amzi! Dynamic/Shared Library - The Amzi! Logic Server, amzi.dll or libamzi.so, and the Amzi! Java interface, amzijni.dll, must be in your PATH or otherwise accessible to the calling environment. These files are in the amzi/\bin directory. You can load these libraries (and LSXs) explicitly in Java with Runtime.getRuntime().load(libraryPath) or loadLibrary(libraryName).
• Amzi! Java Classes - The amzi/ls directory structure, containing the amzi.ls.* package must be accessible via your CLASSPATH. You can do this by adding amzi/lsapis/java20 to your CLASSPATH or copying the amzi/ls subdirectory structure to a directory already in your CLASSPATH.

Hello Prolog

javac Hello.java

java Hello

Overview

So, the Amzi! Java interface defines a Java class, LogicServer, whose methods are implemented by calls to C/C++ functions in a dynamic/shared libary that, in turn, calls the main Amzi! engine dynamic/shared library. This is illustrated in Figure 1.

Figure 1

Working right to left in the diagram, amzi.dll is the Amzi! Logic Server (Prolog engine). amzijni.dll/libamzijni.so is the interface library that implements the Java versions of Logic Server API functions. Those, in turn are wrapped in the Java classes, LogicServer and LSException.

Object Oriented

Figure 2 is an expanded architecture diagram that illustrates the package and its classes.

Figure 2

Representing Prolog Terms

Issuing Prolog Queries

For Java, the query LSAPI functions (Exec, ExecStr, Call, CallStr) return the term (a long) directly, instead of a true false. If the query fails, that is indicated by a zero (0) value returned. (Errors are indicated by LSExceptions.)

String Conversion

Exceptions

Multi-Threaded

Using the Java Class

import amzi.ls.*;

From there you can either instantiate a new LogicServer object and invoke its methods, or you can define a new class that extends the LogicServer class adding new methods and variables.

Implementing Extended Predicates

The Java methods that implement extended predicates, must be declared as returning type boolean, and as public. They can be added one at a time using the API function AddPred, which adds a single predicate at a time. If your extended predicate is in a package, then the package name must be included in the class name, delimited by forward slashes, to AddPred as follows:

ls.AddPred("extpred", 1, "javapkg/jprolog", "extpred", this);

The parameters are:

• Predicate Name
• Predicate Arity
• Java Class Name (fully qualified including packages)
• Java Method Name
• Pointer to the Instance of the Class Object that contains the Method

Note: Extended predicate definitions must always be added after calling InitLS and before calling LoadXPL.

The sample in directory /samples/java/pets_callback is an example of how to implement an extended predicate in Java.

Using Static Methods as Extended Predicates

You can use static methods as extended predicates by specifying null for the pointer to the instance of the class. Static methods are a good choice when pooling Logic Servers in a Web application.

Controlling the JNI Environment Pointer for Extended Predicates

More complex applications may require finer control over the JNI environment pointer that is used to locate and call extended predicates. AddPred can be called with an additional parameter that specifies this, for example:

ls.AddPred("extpred", 1, "javapkg/jprolog", "extpred", this, LogicServer.ADD_PRED);

There are three options:

• ADD_PRED — This uses the JNI environment pointer when AddPred is called. For this to work, the thread that called AddPred() needs to be the same thread that is calling the extended predicate.
• CURRENT_THREAD — This uses the JNI environment pointer for the currently executing thread.
• EXEC_OR_CALL — Not recommend. This option is available for backwards compatibility. It will not work in a multi-threaded environment. It uses the JNI environment pointer from the last Exec(), Call() or Redo(). This pointer is saved in a global variable for all threads using the Amzi! JNI Interface.

Note: Extended predicates will fail (return false) if you use CURRENT_THREAD and the current thread is not attached to the Java virtual machine.

Converting Prolog Lists to Java Types

Here are some useful Java methods that convert Prolog lists. The first takes each item in a Prolog list, converts it to a string and saves it in a String array.

   	public static String[] prologListToStringArray(LogicServer ls, long list, int size) throws LSException
   	{
		List array = new ArrayList();

      	// Check for the empty list or an atom
      	long type = ls.GetTermType(list);

      	if (type != LogicServer.pLIST) return new String[0];

      	while (list != 0) {
         	array.add(ls.TermToStr(ls.GetHead(list), size));

         	list = ls.GetTail(list);
      	}

		String[] result= new String[array.size()];
		array.toArray(result);
		return result;
   }

This method takes a Prolog list of the form [name1 : value1, name2 : value2... nameN: valueN] or [item(name1, value1), item(name2, value2)...item(nameN, valueN)] and converts it to a Java Properties list where the property name and value.

   public static Properties prologListToProperties(LogicServer ls, long list, int size) throws LSException
   {
      Properties p = new Properties();
      long element, name, value;

      // Check for the empty list or an atom
      long type = ls.GetTermType(list);
      if (type != LogicServer.pLIST) return p;

      while (list != 0) {
         element = ls.GetHead(list);
         name = ls.GetArg(element, 1);
         value = ls.GetArg(element, 2);
         if (ls.GetTermType(value) == LogicServer.pLIST)
            p.setProperty(ls.TermToStr(name, size), ls.TermToStrQ(value, size));
         else {
			p.setProperty(ls.TermToStr(name, size), ls.TermToStr(value, size));
         }

         list = ls.GetTail(list);
      }
      return p;
   }

Examples

Samples for .NET can be found in samples\java and in samples\internet\jsp and samples\internet\servlets.

Copyright ©1987-2011 Amzi! inc. All Rights Reserved. Amzi! is a registered trademark and Logic Server is a trademark of Amzi! inc.