protocol

# `java_utils_protocol`

Abstract interface to Java utility predicates.

Availability:
`logtalk_load(java(loader))`
Author: Paulo Moura
Version: 1:6:0
Date: 2023-03-13
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `value_reference/2`

Returns an opaque term that represents the Java value with the given name.

Compilation flags:
`static`
Template:
`value_reference(Value,Reference)`
Mode and number of proofs:
`value_reference(?atom,--ground)` - `one_or_more`

### `true/1`

Returns an opaque term that represents the Java value true.

Compilation flags:
`static`
Template:
`true(Reference)`
Mode and number of proofs:
`true(--ground)` - `one`

### `false/1`

Returns an opaque term that represents the Java value false.

Compilation flags:
`static`
Template:
`false(Reference)`
Mode and number of proofs:
`false(--ground)` - `one`

### `void/1`

Returns an opaque term that represents the Java value void.

Compilation flags:
`static`
Template:
`void(Reference)`
Mode and number of proofs:
`void(--ground)` - `one`

### `null/1`

Returns an opaque term that represents the Java value null.

Compilation flags:
`static`
Template:
`null(Reference)`
Mode and number of proofs:
`null(--ground)` - `one`

### `is_true/1`

True when the argument is the Java value true. Fails if the argument is not instantiated.

Compilation flags:
`static`
Template:
`is_true(Reference)`
Mode and number of proofs:
`is_true(@term)` - `zero_or_one`

### `is_false/1`

True when the argument is the Java value false. Fails if the argument is not instantiated.

Compilation flags:
`static`
Template:
`is_false(Reference)`
Mode and number of proofs:
`is_false(@term)` - `zero_or_one`

### `is_void/1`

True when the argument is the Java value void. Fails if the argument is not instantiated.

Compilation flags:
`static`
Template:
`is_void(Reference)`
Mode and number of proofs:
`is_void(@term)` - `zero_or_one`

### `is_null/1`

True when the argument is the Java value null. Fails if the argument is not instantiated.

Compilation flags:
`static`
Template:
`is_null(Reference)`
Mode and number of proofs:
`is_null(@term)` - `zero_or_one`

### `is_object/1`

True when the argument is a reference to a Java object. Fails if the argument is not instantiated.

Compilation flags:
`static`
Template:
`is_object(Reference)`
Mode and number of proofs:
`is_object(@term)` - `zero_or_one`

### `terms_to_array/2`

Converts a list of ground Prolog terms to an array (a Java reference).

Compilation flags:
`static`
Template:
`terms_to_array(Terms,Array)`
Mode and number of proofs:
`terms_to_array(++list(ground),-array)` - `one`

### `array_to_terms/3`

Converts an array (a Java reference) to a list of ground Prolog terms returning also its length. The array elements must be atoms, integers, floats, or compound terms. Fails otherwise.

Compilation flags:
`static`
Template:
`array_to_terms(Array,Terms,Length)`
Mode and number of proofs:
`array_to_terms(+array,-list(ground),-integer)` - `one`

### `array_to_terms/2`

Converts an array (a Java reference) to a list of ground Prolog terms. The array elements must be atoms, integers, floats, or ground compound terms. Fails otherwise.

Compilation flags:
`static`
Template:
`array_to_terms(Array,Terms)`
Mode and number of proofs:
`array_to_terms(+array,-list(term))` - `one`

### `array_to_list/2`

Converts an array (a Java reference) to a list of Java references or their values.

Compilation flags:
`static`
Template:
`array_to_list(Array,List)`
Mode and number of proofs:
`array_to_list(+array,-list)` - `one`

### `list_to_array/2`

Converts a list of Java references or values to an array (a Java reference).

Compilation flags:
`static`
Template:
`list_to_array(List,Array)`
Mode and number of proofs:
`list_to_array(+list,-array)` - `one`

### `array_list/2`

Converts between an array (a Java reference) and a list of Java references or their values. Deprecated. Use the `array_to_list/2` and `list_to_array/2` predicates instead.

Compilation flags:
`static`
Template:
`array_list(Array,List)`
Mode and number of proofs:
`array_list(+array,-list)` - `one`
`array_list(-array,+list)` - `one`

### `iterator_element/2`

Enumerates, by backtracking, all iterator elements.

Compilation flags:
`static`
Template:
`iterator_element(Iterator,Element)`
Mode and number of proofs:
`iterator_element(+iterator,-element)` - `zero_or_more`

### `map_element/2`

Enumerates, by backtracking, all map elements.

Compilation flags:
`static`
Template:
`map_element(Map,Element)`
Mode and number of proofs:
`map_element(+iterator,-element)` - `zero_or_more`

### `set_element/2`

Enumerates, by backtracking, all set elements.

Compilation flags:
`static`
Template:
`set_element(Set,Element)`
Mode and number of proofs:
`set_element(+iterator,-element)` - `zero_or_more`

### `decode_exception/2`

Decodes an exception into its corresponding cause. Fails if the exception is not a Java exception.

Compilation flags:
`static`
Template:
`decode_exception(Exception,Cause)`
Mode and number of proofs:
`decode_exception(+callable,-atom)` - `zero_or_one`

### `decode_exception/3`

Decodes an exception into its corresponding cause and a stack trace. Fails if the exception is not a Java exception.

Compilation flags:
`static`
Template:
`decode_exception(Exception,Cause,StackTrace)`
Mode and number of proofs:
`decode_exception(+callable,-atom,-list(atom))` - `zero_or_one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)