.. index:: single: java_utils_protocol
.. _java_utils_protocol/0:

.. rst-class:: right

**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)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: value_reference/2
.. _java_utils_protocol/0::value_reference/2:

``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``


------------

.. index:: true/1
.. _java_utils_protocol/0::true/1:

``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``


------------

.. index:: false/1
.. _java_utils_protocol/0::false/1:

``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``


------------

.. index:: void/1
.. _java_utils_protocol/0::void/1:

``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``


------------

.. index:: null/1
.. _java_utils_protocol/0::null/1:

``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``


------------

.. index:: is_true/1
.. _java_utils_protocol/0::is_true/1:

``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``


------------

.. index:: is_false/1
.. _java_utils_protocol/0::is_false/1:

``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``


------------

.. index:: is_void/1
.. _java_utils_protocol/0::is_void/1:

``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``


------------

.. index:: is_null/1
.. _java_utils_protocol/0::is_null/1:

``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``


------------

.. index:: is_object/1
.. _java_utils_protocol/0::is_object/1:

``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``


------------

.. index:: terms_to_array/2
.. _java_utils_protocol/0::terms_to_array/2:

``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``


------------

.. index:: array_to_terms/3
.. _java_utils_protocol/0::array_to_terms/3:

``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``


------------

.. index:: array_to_terms/2
.. _java_utils_protocol/0::array_to_terms/2:

``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``


------------

.. index:: array_to_list/2
.. _java_utils_protocol/0::array_to_list/2:

``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``


------------

.. index:: list_to_array/2
.. _java_utils_protocol/0::list_to_array/2:

``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``


------------

.. index:: array_list/2
.. _java_utils_protocol/0::array_list/2:

``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``


------------

.. index:: iterator_element/2
.. _java_utils_protocol/0::iterator_element/2:

``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``


------------

.. index:: map_element/2
.. _java_utils_protocol/0::map_element/2:

``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``


------------

.. index:: set_element/2
.. _java_utils_protocol/0::set_element/2:

``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``


------------

.. index:: decode_exception/2
.. _java_utils_protocol/0::decode_exception/2:

``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``


------------

.. index:: decode_exception/3
.. _java_utils_protocol/0::decode_exception/3:

``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)