api
Author: Paul Singleton

# JPL 3.x Prolog API reference

jpl_new( +ClassOrType, +Params, -Result)
  unifies Result with a JPL reference to a new instance of ClassOrType, constructed with Params, e.g. `jpl_new('javax.swing.JFrame', ['JPL demo'], F)`. There are many other ways to call this predicate: see BlahBlah.
jpl_call( +Object, +Method, +Params, -Result)
  unifies Result with a JPL reference to (or value of) the result of calling the named method of Object with Params, e.g. `jpl_call(F, setVisible, [@(true)], _)`. There are many other ways to call this predicate: see BlahBlah.
jpl_get( +Object, +Field, -Value)
  unifies Value to the value of, or a reference to, the named field of Object. There are many other ways to call this predicate: see BlahBlah..
jpl_set( +Object, +Field, +Value)
  sets the named field of Object to Value (a JPL reference or value). There are many other ways to call this predicate: see BlahBlah..

##
Java inspection

jpl_class_to_classname( +Class, -Classname)
  Class must be a JPL reference to a Java class object (i.e. an instance of java.lang.Class); Classname is its canonical dotted name, e.g. `'java.util.Date'`.
jpl_class_to_type( +Class, -Type)
  Class must be a JPL reference to a Java class object (i.e. an instance of java.lang.Class); Type is its JPL type, e.g. `class([java,util],['Date'])` or `array(double)`.
jpl_classname_to_class( +Classname, -Class)
  Classname must be a canonical dotted name (an atom) of a Java class, e.g. `'java.util.Date'`; Class is a JPL reference to a corresponding Java class object (i.e. an instance of java.lang.Class).
jpl_classname_to_type( +Classname, -Type)
  Classname must be a canonical dotted name (an atom) of a Java class, e.g. `'java.util.Date'`; Type is its JPL type, e.g. `class([java,util],['Date'])`.
jpl_datum_to_type( +Datum, -Type)
  Datum must be a valid JPL representation of some Java object or value e.g. `3`, `fred`, `@(false)`; Type is its JPL type, e.g. `char_byte`, `class([java,lang],['String'])`, `boolean`.
jpl_false( -Datum)
  Datum is the JPL representation of the Java boolean value false, i.e. `@(false)`.
jpl_is_class( ?Term)
  Term is a JPL reference to a Java class object, i.e. to an instance of java.lang.Class. No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_false( ?Term)
  Term is the JPL representation of the Java boolean value false. No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_null( ?Term)
  Term is a JPL representation of the Java boolean value null. No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_object( ?Term)
  Term is a JPL reference to a Java object. No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_object_type( ?Term)
  Term is a JPL class or array type (but not `null`, `void`, or one of the primitive types). No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_ref( ?Term)
  Term is a JPL class or array type, or is `null` (i.e. the JPL type of Java's null reference) (but not `void` or one of the primitive types). No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_true( ?Term)
  Term is the JPL representation of the Java boolean value true. No further instantiation of Term will take place; if it is not ground, this predicate fails.
jpl_is_type( ?Term)
  Term is a JPL type, e.g. `char_byte`, `float`, `array(int)`. No further instantiation of Term will take place; if it not ground, this predicate fails.
jpl_is_void( ?Term)
  Term is the JPL representation of the (notional but convenient) Java value void, i.e. `@(void)`. No further instantiation of Term will take place; if it not ground, this predicate fails.
jpl_null( -Datum)
  Datum is the JPL representation of the Java null reference null.
jpl_object_to_class( +Object, -Class)
  Object is a JPL reference to a Java object; Class is a JPL reference to a Java class object (an instance of java.lang.Class) which represents Object's class.
jpl_object_to_type( +Object, -Type)
  Object is a JPL reference to a Java object; Type is its JPL type, e.g. `array(boolean)`, `class([javax,sql],['Timestamp'])`.
jpl_primitive_type( -Type)
  Type is one of the JPL primitive types `boolean`, `char`, `byte`, `short`, `int`, `long`, `float`, `double`.
jpl_ref_to_type( +Ref, -Type)
  Ref is a JPL reference to a Java object; Type is the JPL type of Object, e.g. `array(boolean)`, `class([javax,sql],['Timestamp'])`.
jpl_true( -Datum)
  Datum is the JPL representation of the Java boolean value true.
jpl_type_to_class( +Type, -Class)
  Type is a JPL class (or array) type, e.g. `class([javax,sql],['Timestamp'])` or `array(boolean)`; Class is a JPL reference to a Java class object (an instance of java.lang.Class) which corresponds to Type.
jpl_type_to_classname( +Type, -Classname)
  Type is a JPL class (or array) type, e.g. `class([javax,sql],['Timestamp'])` or `array(boolean)`; Classname is its canonical dotted name (an atom).
jpl_void( -Datum)
  Datum is the JPL representation of the (notional but convenient) Java value void, i.e. `@(void)`.

##
Utilities

jpl_array_to_length( +Array, -Length)
  Array is a JPL reference to a Java array; Length is its length (an integer).
jpl_array_to_list( +Array, -ListOfDatums)
  Array is a JPL reference to a Java array (of any base type); ListOfDatums is a (Prolog) list of JPL references to, or values of, its respective elements.
jpl_datums_to_array( +ListOfDatums, -Array)
  ListOfDatums is a (Prolog) list of JPL references or values; Array is a JPL reference to a Java array of corresponding objects or values. The base type of Array is the most specific Java type of which each member of ListOfDatums is (directly or indirectly) an instance. If there is no such type, this predicate fails. Values of Java primitive types are not automatically "boxed". Lists which are mixtures of numbers, booleans and object references cannot be converted to Java arrays with this predicate.
jpl_enumeration_element( +Enumeration, -Element)
  Enumeration is a JPL reference to a Java object whose class implements the java.util.Enumeration interface; Element is an element of Enumeration. This predicate can generate each element of an enumeration.
jpl_enumeration_to_list( +Enumeration, -ListOfElement)
  Enumeration is a JPL reference to a Java object whose class implements the java.util.Enumeration interface; ListOfElement is a list of JPL references to each element of Enumeration.
jpl_hashtable_pair( +Hashtable, -KeyValuePair)
  Hashtable is a JPL reference to a Java hashtable object (an instance of java.util.Hashtable); KeyValuePair is a `-/2` compound term whose first arg is a key (atom or ref) from Hashtable, and whose second arg is its corresponding value (atom or ref), e.g.`fred-@'J#0008127852'`.
jpl_iterator_element( +Iterator, -Element)
  Iterator is a JPL reference to a Java object whose class implements the java.util.Iterator interface; Element is a JPL reference to one of its elements. This predicate can generate all elements.
jpl_list_to_array( +ListOfDatum, -Array)
  This is a synonym for jpl_datums_to_array/2, in case you forget that JPL values and references are called "datums".
jpl_map_element( +Map, -KeyValuePair)
  Map is a JPL reference to a Java object whose class implements the java.util.Map interface; KeyValuePair is a `-/2` compound term whose first arg is a key (atom or ref) from Map, and whose second arg is its corresponding value (atom or ref), e.g.`-(fred,@'J#0008127852'`), or `fred-@'J#0008127852'` using conventional operator definitions.
jpl_set_element( +Set, -Element)
  Set is a JPL reference to a Java object whose class implements the java.util.Set interface; Element is a JPL reference to an object (or null) within Set. This predicate can generate all elements of Set

##
Miscellaneous

jpl_c_lib_version( -Version)
  unifies Version to an atom (e.g. `'3.0.1-alpha'`) whose name is the version identifier of the 'C' library which JPL is using.
jpl_c_lib_version( -Major, -Minor, -Patch, -Status)
  unifies Major, Minor, Patch and Status to the corresponding components (e.g. `3`, `0`, `1` and `alpha`) of the version identifier of the 'C' library which JPL is using.