Type Mapping for Inter-language Operations

Overview

PrologJ uses objects belonging to several Java classes to represent various kinds of terms. Some of these are standard Java classes, while others are specific to this implementation of Prolog.

• Prolog atoms are represented internally by Java String objects, whose value is the name of the atom.
   
  
• Prolog integers are represented internally by Java Integer and BigInteger objects. PrologJ uses Integer to represent any value that can be represented as a 32-bit two's complement integer, and uses BigInteger for larger values. Conversion between the two is performed automatically and seamlessly - e.g. if two Integer objects are added and the result is too big to be stored as a 32-bit two's complement integer, then the result is automatically converted to BigInteger; and if two BigInteger objects are subtracted and the result is now small enough to represent as a 32-bit two's complement integer, then the result is converted to an Integer.
   
  
• Prolog floats are represented internally by Java Double objects.
   
  
• Prolog compound terms are represented internally by a class defined in the PrologJ implementation. Certain operations are possible on objects of this class outside of the PrologJ implementation, as specified the interface PrologCompound.
   
  
  • Prolog lists are a special kind of compound term, and also implement this interface; in addition, they implement the PrologList interface.
     
    
  • Prolog streams are a special kind of compound term, and also implement this interface. However, no access to the actual stream they encapsulate is possible from outside the PrologJ implementation beyond access to the name of the stream. (The interface methods behave as if the term were the compound term '$stream'(name) or '$closed_stream'(Formerly name)).
   
  
• PrologJ uses an internal representation for variables that is not accessible from outside the implementation. If code that is not part of the PrologJ implementation attempts to access an object that is an instantiated variable, it is given the object to which that variable is instantiated; if it tries to access an uninstantiated variable, it is given the value null.
   
  
• The inter-language facilites of PrologJ typically convert an object of some other class to one of the above whenever it is possible to do so without losing information. (See the table below). However, PrologJ also allows an object of an arbitrary Java class to be manipulated in limited ways. This allows inter-language code to store arbitrary objects in the Prolog database and later retrieve them, or to instantiate a Prolog variable to an arbitrary object that will later be used as a parameter to some non-Prolog method or stored in some non-Prolog field. PrologJ only allows the following operations on such object terms:
   
  
  • An object term may be written using built-in predicates like write. The written form is <object result of the object's toString() method>.
     
    
  • An object term may be unified with an uninstantiated variable, in which case the variable is instantiated to it, as with any other Prolog term.
     
    
  • An object term may be unified with any term, in which case unification succeeds only if the equals() method inherited from class Object is true.

Conversions from other Language Types

The inter-language facilities of PrologJ allow various types of non-Prolog value to be used by Prolog. A fundamental principle is that a non-Prolog type is converted to an equivalent Prolog type in such a way as to not lose information, if this is possible. The table below shows these conversions. (If the type of the object is not one of those listed here, it is manipulated internally by PrologJ as an object term, as discussed above).

Standard Conversions between other Language Types and Prolog Types

The following table shows standard conversions between Java types, SQL types, and Prolog terms. The column labelled "Prolog Term Type Converted To" indicates the Prolog type that a Java or SQL value will be converted to when it is sent to the PrologJ system. The column labelled "Prolog Term Types Converted From" indicates the types of Prolog term that can be converted to the specified type when called for by Java or SQL or an explicit parameter specifier.

Java Data Type	SQL Type	Prolog Term Type Converted To	Prolog Term Types Converted From
boolean Boolean	BOOLEAN	The atom true or fail	The atom true fail or false uninstantiated variable *
char Character	-	A one character atom	A one character atom uninstantiated variable *
-	BIT	The integer 0 or 1	The integer 0 or 1 The atom true fail or false
byte Byte short Short int Integer long Long BigInteger	TINYINT SMALLINT INTEGER BIGINT	integer #	integer ## uninstantiated variable *
float Float double Double	REAL FLOAT DOUBLE	float +	integer float ++ uninstantiated variable *
-	DECIMAL or NUMERIC with scale factor zero	integer #	integer &&
-	Any other DECIMAL or NUMERIC	float &	integer && float &&
String	CHAR VARCHAR LONGVARCHAR	atom	atom integer float proper list of codes proper list of characters uninstantiated variable *
PrologCompound but not PrologList	-	compound term	compound term uninstantiated variable *
PrologList	-	any kind of list	any kind of list uninstantiated variable *
array	-	proper list @ [] @@	proper list @ [] @@ uninstantiated variable *
-	DATE	object of class  java.sql.Date	object of class  java.sql.Date An atom parseable  as a SQL DATE
-	TIME	object of class  java.sql.Time	object of class  java.sql.Time An atom parseable  as a SQL TIME
-	TIMESTAMP	object of class  java.sql.Timestamp	object of class  java.sql.Timestamp An atom parseable  as a SQL TIMESTAMP
null (of any type)	NULL	uninstantiated variable
Any other non-primitive	OTHER Any other type	object term of the same class	object term of the same class uninstantiated variable *

* An uninstantiated variable can be converted to null of any Java reference type, or can be stored into or compared with a SQL column of any type that is not declared not null. An instantiation_error is reported if an attempt is made to convert an uninstantiated variable to a primitive type or to store it into or compare it with a column that is declared not null.

# Since PrologJ uses both Integer and BigInteger internally for integers, any value of these types can be represented without loss of information. Integer is used wherever possible.

## If the Prolog value doesn't "fit" in the Java or SQL type, the value passed to Java or SQL will be truncated in the same way that a value is trucated by the methods byteValue(), shortValue(), intValue(), or longValue specified in the class java.lang.Number.

+ Since PrologJ uses Double internally for floats, any value can generally be represented without loss of information. The exception would be a SQL FLOAT if the DBMS allows the number of digits of precision specified to exceed what is possible for a 64 bit representation.

++ If the Java or SQL type is a 32-bit floating point value, some precision may be lost, or the result may be an IEEE infinity; it will be truncated in the same way that a value is trucated by the method floatValue() specified in the class java.lang.Number.

& The SQL value may be represented inexactly, since SQL NUMERIC or DECIMAL is a fixed point data type. Also, if the SQL value lies outside the range of a Java double, the result may be an IEEE infinity.

&& If the Prolog value doesn't "fit" in the width specified for the SQL NUMERIC or DECIMAL column, the result may be truncated.

@ The elements of the list are converted according to the rules for the declared type of the elements of the array. This extends to allowing an array of arrays to be converted to/from a list of lists, etc.

@@ The empty list ([]) is equivalent to an array of length 0.

The following SQL data types are not directly supported. Columns based on these values can be converted to/from Java objects according to the type conversion rules of JDBC, but the Java objects typically cannot be operated upon by Prolog programs.

• ARRAY
• BINARY
• BLOB
• CLOB
• DATALINK
• DISTINCT
• JAVA_OBJECT
• LONGVARBINARY
• OTHER
• REF
• STRUCT
• VARBINARY

Error Cases

The following error cases are detected when arg/3 attempts to store a value in to a field, or a relational database predicate either stores a value into a column in a table or compares a value with a column in a table, or when a list of terms is converted to an array. The term "target type" refers to the declared type of the field, database table column, or array components, as the case may be.

Conditions	Error Term
The target type is a primitive type, and the value is a variable	instantiation_error
The target type is boolean or Boolean or the SQL type BOOLEAN, and the value V is neither a variable nor true nor fail nor false	type_error(boolean, V)
The target type is char or Character and the value V is neither a variable nor a one-character atom	type_error(character, V)
The target type is byte, Byte, short, Short, int, Integer, long, Long or BigInteger or one of the SQL types TINYINT, SMALLINT, INTEGER, or BIGINT, and the value V is neither a variable nor an integer	type_error(integer, V)
The target type is float, Float, double or Double or one of the SQL types REAL, FLOAT, or DOUBLE, NUMERIC, or DECIMAL, and the value V is neither a variable nor a number	type_error(number, V)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value V is a partial list	instantiation_error
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value V is an improper list	type_error(list, V)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value V is a list which contains an element that is a variable	instantiation_error
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value is a list whose first element is an atom, and the list contains an element E that is not a one_character atom	type_error(character, E)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value is a list whose first element is an integer, and the list contains an element E that is not an integer	type_error(integer, E)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value is a list whose first element is an integer, and the list contains an element E that is an integer that is not a valid character code	representation_error(character_code)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value is a list whose first element E is neither a variable, nor an atom, nor an integer	type_error(integer, E)
The target type is String or one of the SQL types CHAR, VARCHAR, or LONGCHAR, and the value V is neither a variable, nor atomic, nor a list	type_error(atomic, E)
The target type is PrologCompound, and the value V is neither a variable nor a compound term	type_error(compound, V)
The target type is PrologList, and the value V is neither a variable nor a list	type_error(list, V)
The target type is the SQL type BIT, and the value V is neither a variable nor the atoms true, fail or false nor the numbers 0 or 1	representation_error(bit)
The target type is the SQL type DATE, and the value V is an atom that is not a jdbc date escape	system_error(illegal_argument, V)
The target type is the SQL type DATE, and the value V is neither a variable, nor an atom, nor a Java object of class java.sql.Date	type_error(atom, V)
The target type is the SQL type TIME, and the value V is an atom that is not a jdbc time escape	system_error(illegal_argument, V)
The target type is the SQL type TIME, and the value V is neither a variable, nor an atom, nor a Java object of class java.sql.Time	type_error(atom, V)
The target type is the SQL type TIMESTAMP, and the value V is an atom that is not a jdbc timestamp escape	system_error(illegal_argument, V)
The target type is the SQL type TIMESTAMP, and the value V is neither a variable, nor an atom, nor a Java object of class java.sql.Timestamp	type_error(atom, V)
The target type is an array, and the value is a partial list	instantiation_error
The target type is an array, and the value V is an improper list	type_error(list, V)
The target type is an array, and the value V is neither a variable, nor a list, nor the empty list	type_error(list, V)
The target type is an array, and the value V is a list which contains an element that is not convertable to the component type of the array	as specified above, taking the component type of the array to be the target type and the list element to be the value

Copyright © 2005 - Russell C. Bjork. See the file See file COPYING in the root directory for copyright information.