CiaoJava
Class PLInterpreter

java.lang.Object
  |
  +--CiaoJava.PLInterpreter

class PLInterpreter
extends java.lang.Object

This class interprets the terms received from the Prolog side and performs the actions requested from that side. This class is used by almost every class of the CiaoJava package because contains the object table needed to look up the Java objects referred by the Prolog side.


Field Summary
private static java.lang.String ADD_LISTENER
           
private static java.lang.String CREATE_OBJECT
           
private static java.lang.String DELETE_OBJECT
           
private  PLEventListener eventListener
           
private static float FACTOR
           
private static java.lang.String GET_VALUE
           
private static java.lang.String INVOKE_METHOD
           
private  int objKey
           
private  java.util.Hashtable objTable
           
private static java.lang.String QUIT
           
private static java.lang.String REMOVE_LISTENER
           
private static java.lang.String SET_VALUE
           
private static int STARTING_CAPACITY
           
private static java.lang.String WAIT_FOR_EVENTS
           
 
Constructor Summary
PLInterpreter(PLConnection pl)
          Creates a new interpreter, with the table of objects managed by Prolog given as argument.
 
Method Summary
private  PLTerm addListener(PLStructure st)
          Adds the Java object event to the listener predicate.
private  PLTerm createObject(PLStructure st)
          Creates a Java object and adds it to the object table.
private  PLTerm deleteObject(PLStructure st)
          Deletes a Java object and removes it from the object table.
private  java.lang.reflect.Constructor getConstructor(java.lang.Class cl, java.lang.Class[] clsarg)
          Gets the constructor of the class cl that matches the parameter type object array.
private  int getDistance(java.lang.Class assignedTo, java.lang.Class assignedFrom)
          Gets a measure of the 'distance' between two assignable classes.
private  java.lang.reflect.Method getMethod(java.lang.Class cl, java.lang.String mtName, java.lang.Class[] clsarg)
          Gets the method of the class cl that matches the parameter type object array.
 java.lang.Object getObject(java.lang.Integer hashCode)
          Gets the object from the object table given the hash code.
private  PLTerm getValue(PLStructure st)
          Gets the value of a Java object field.
 PLTerm interpret(PLTerm t)
          Interprets the request received as argument in a PLTerm object.
private  java.lang.Object invoke(java.lang.reflect.Method mt, java.lang.Object obj, java.lang.Object[] arg)
          Invokes the method received as first argument on the object received as second argument, with the arguments of the third argument.
private  PLTerm invokeMethod(PLStructure st)
          Invokes a Java object method.
static boolean isInterpretable(PLTerm t)
          Returns true if the term received as argument can be interpreted by the Prolog term interpreter.
private  PLTerm java_object(int i)
          Prolog representation of a Java object in the object table.
private  PLTerm prologRepr(java.lang.Object v)
          Gets the Prolog representation of the object argument.
private  PLTerm removeListener(PLStructure st)
          Removes the Java object event from the listener predicate.
private  PLTerm setValue(PLStructure st)
          Sets the value of a Java object field.
private  java.lang.Object translateArg(java.lang.Object arg, java.lang.Class type)
          Argument translation for method/constructor invocation.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

objTable

private java.util.Hashtable objTable

objKey

private int objKey

STARTING_CAPACITY

private static final int STARTING_CAPACITY

FACTOR

private static final float FACTOR

eventListener

private PLEventListener eventListener

CREATE_OBJECT

private static final java.lang.String CREATE_OBJECT

DELETE_OBJECT

private static final java.lang.String DELETE_OBJECT

GET_VALUE

private static final java.lang.String GET_VALUE

SET_VALUE

private static final java.lang.String SET_VALUE

INVOKE_METHOD

private static final java.lang.String INVOKE_METHOD

ADD_LISTENER

private static final java.lang.String ADD_LISTENER

REMOVE_LISTENER

private static final java.lang.String REMOVE_LISTENER

QUIT

private static final java.lang.String QUIT

WAIT_FOR_EVENTS

private static final java.lang.String WAIT_FOR_EVENTS
Constructor Detail

PLInterpreter

public PLInterpreter(PLConnection pl)
Creates a new interpreter, with the table of objects managed by Prolog given as argument.
Parameters:
pl - Object that represents the connection to the Prolog process.
Method Detail

interpret

public PLTerm interpret(PLTerm t)
Interprets the request received as argument in a PLTerm object. The possible requests are the following (the arguments of the Prolog terms described are marked as input or output arguments with the plus or minus sign; and the output arguments are not actually included in the terms, only show what requests send back results to Prolog): $java_create_object(+NAME, +ARGUMENTS, -OBJECT) Creates a new Java instance of the class given as NAME (full class name), using the appropriate constructor to the arguments given in ARGUMENTS, and returns to Prolog an object identifier. $java_delete_object(+OBJECT) Deletes the object with identifier equal to OBJECT. $java_get_value(+OBJECT, +FIELD, -VALUE) Gets the value of the field FIELD from the object OBJECT, and returns to Prolog its value. $java_set_value(+OBJECT, +FIELD, +VALUE) Sets the value of the field FIELD of the object identified with the OBJECT reference to the value received as VALUE. $java_invoke_method(+OBJECT, +METHOD, +ARGUMENTS, -RESULT) Invokes the corresponding method of the object referred as OBJECT using the given arguments, and sends back the result to Prolog (if the method returns a result). $java_add_listener(+OBJECT, +EVENT, +PREDICATE, -RESULT) Adds a goal to the list of Prolog listeners for a given object event. The EVENT argument must be the full class name of the Java event object representing the event (e.g., java.awt.event.ActionListener). $java_remove_listener(+OBJECT, +EVENT, +PREDICATE, -RESULT) Removes a Prolog listener from the list of event handlers for a given event and object. $quit Closes the connection and terminates the Java process.
Parameters:
t - Prolog term to be interpreted. Only Are interpreted the Prolog terms related above.
Returns:
the term to be sent back to Prolog, corresponding to the returning value. If there is no return value, the success atom is returned. If an error occurs a java_exception is returned to be propagated to the Prolog side.

getValue

private PLTerm getValue(PLStructure st)
Gets the value of a Java object field. Evaluates the '$java_get_value' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference and field name.
Returns:
The Prolog representation of the field value requested, if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

setValue

private PLTerm setValue(PLStructure st)
Sets the value of a Java object field. Evaluates the '$java_set_value' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference, field name and field value.
Returns:
the Prolog representation of success if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

deleteObject

private PLTerm deleteObject(PLStructure st)
Deletes a Java object and removes it from the object table. Evaluates the '$java_delete_object' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference.
Returns:
the Prolog representation of success if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

createObject

private PLTerm createObject(PLStructure st)
Creates a Java object and adds it to the object table. Evaluates the '$java_create_object' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: class name and constructor argument list.
Returns:
the Prolog representation of the Java object if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

invokeMethod

private PLTerm invokeMethod(PLStructure st)
Invokes a Java object method. Evaluates the '$java_invoke_method' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference, method name and argument list.
Returns:
the Prolog representation of the value returned by the Java method call if the command succeeds; the Prolog representation of success if the method invocation does not return a value; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

addListener

private PLTerm addListener(PLStructure st)
Adds the Java object event to the listener predicate. Evaluates the '$java_add_listener' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference, event class name and exception handler goal.
Returns:
the Prolog representation of success if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

removeListener

private PLTerm removeListener(PLStructure st)
Removes the Java object event from the listener predicate. Evaluates the '$java_remove_listener' Prolog term, given as argument.
Parameters:
st - Prolog structure that contains the data needed for this operation: object reference, event class name and exception handler goal.
Returns:
the Prolog representation of success if the command succeeds; a PLStructure representing a Java exception to be sent back to Prolog if the Prolog request does not succeed.

prologRepr

private PLTerm prologRepr(java.lang.Object v)
Gets the Prolog representation of the object argument.
Parameters:
v - Java object from which a Prolog representation will be obtained.
Returns:
the Prolog term that represents the Java object received as argument.

java_object

private PLTerm java_object(int i)
Prolog representation of a Java object in the object table.
Parameters:
i - hash code in the object table.
Returns:
a new PLTerm object that references the object referenced by the hash code.

getMethod

private java.lang.reflect.Method getMethod(java.lang.Class cl,
                                           java.lang.String mtName,
                                           java.lang.Class[] clsarg)
Gets the method of the class cl that matches the parameter type object array. Considers superclass and interface matching using the isAssignableFrom() method (of the Class class). The main concern about searching the method to be launched for a given object, method name, and parameter types is to choose from method candidates that are compatible with the parameter types. In most of cases will be no possibility of discussion, only one method fits the number and parameter types. The problem raises when given the parameter type array, several methods could be called, mainly because the type correspondence between Java and Prolog is not perfect. This method uses the concept of 'distance' to select the best fit for a given parameter array.
Parameters:
cl - Class object that represents the object class.
mtName - Method name.
clsarg - Array of Class objects that represents the method argument list.
Returns:
the Method object that represents the method found. If there is no method in the inheritance tree, returns null.

getConstructor

private java.lang.reflect.Constructor getConstructor(java.lang.Class cl,
                                                     java.lang.Class[] clsarg)
Gets the constructor of the class cl that matches the parameter type object array. Considers superclass and interface matching of the parameters using the isAssignableFrom() method (of the Class class). The algorithm is exactly the same as the used in getMethod. See this method to get detailed information.
Parameters:
cl - Class object that represents the object class.
clsarg - Array of Class objects that represents the constructor argument list.
Returns:
the Constructor object that represents the constructor found. If there is no constructor in the inheritance tree, returns null.

getDistance

private int getDistance(java.lang.Class assignedTo,
                        java.lang.Class assignedFrom)
Gets a measure of the 'distance' between two assignable classes. In order to choose the nearest fit from a list of Java types to a list of methods or constructors, is needed to use an heuristic based on the distance between types. Is supossed that the Java classes received as arguments are compatible using the isAssignableFrom method of the Class class. Is supossed that the assignedFrom parameter will not be primitive.
Parameters:
assignedTo - Class object that represents the Java type to be assigned.
assignedFrom - Class object that represents the Java type from which will be made the assignment.
Returns:
an int number representing the 'distance' between the classes received as argument.

invoke

private java.lang.Object invoke(java.lang.reflect.Method mt,
                                java.lang.Object obj,
                                java.lang.Object[] arg)
                         throws java.lang.Exception
Invokes the method received as first argument on the object received as second argument, with the arguments of the third argument. The method invoke of the class Method cannot be used directly because the argument types could not correspond exactly to the method ones. A kind of conversion must be done with the primitive Java types.
Parameters:
mt - Method to be invoked.
obj - Object on which the method will be invoked.
arg - List of argument values to invoke the method.
Throws:
Exception - if there is any problem invoking the method.

translateArg

private java.lang.Object translateArg(java.lang.Object arg,
                                      java.lang.Class type)
Argument translation for method/constructor invocation. Translates one argument making the type casting needed by the method/constructor.
Parameters:
arg - Argument value received for method/constructor invocation.
type - Primitive type needed by the method/constructor.
Returns:
The argument value with the proper type, if there is any; null if there is no possible conversion.

isInterpretable

public static boolean isInterpretable(PLTerm t)
Returns true if the term received as argument can be interpreted by the Prolog term interpreter.
Parameters:
t - Term to be tested for interpretation.
Returns:
true if the Prolog term received as argument can be interpreted by the Prolog command interpreter (method interpret above).

getObject

public java.lang.Object getObject(java.lang.Integer hashCode)
Gets the object from the object table given the hash code.
Parameters:
hashCode - Hash code that references an object in the Java object table.
Returns:
a Java object referenced by the hash code.