[id='using-functional-map-api']
= Using the Functional Map API

{brandname}'s link:{javadocroot}/org/infinispan/functional/FunctionalMap.html[Functional Map API]
is a distilled map-like asynchronous API which uses functions to interact with data.

== Asynchronous and Lazy

Being an asynchronous API, all methods that return a single result,
return a CompletableFuture which wraps the result, so you can use the
resources of your system more efficiently by having the possibility to
receive callbacks when the
link:{jdkdocroot}/java/util/concurrent/CompletableFuture.html[`CompletableFuture`]
has completed, or you can chain or compose them with other CompletableFuture.

For those operations that return multiple results, the API returns instances of a link:{javadocroot}/org/infinispan/functional/Traversable.html[Traversable] interface which offers a lazy pull-style API for working with multiple results.

`Traversable`, being a lazy pull-style API, can still be asynchronous underneath since the user can decide to work on the traversable at a later stage, and the `Traversable` implementation itself can decide when to compute those results.

== Function transparency

Since the content of the functions is transparent to {brandname}, the API
has been split into 3 interfaces for read-only (
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadOnlyMap.html[`ReadOnlyMap`]
), read-write (
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html[`ReadWriteMap`]
) and write-only (
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html[`WriteOnlyMap`]
) operations respectively, in order to provide hints to the {brandname}
internals on the type of work needed to support functions.

== Constructing Functional Maps

To construct any of the read-only, write-only or read-write map
instances, an {brandname}
link:{javadocroot}/org/infinispan/AdvancedCache.html[`AdvancedCache`]
is required, which is retrieved from the Cache Manager, and using the
link:{javadocroot}/org/infinispan/AdvancedCache.html[`AdvancedCache`]
, static method
factory methods are used to create
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadOnlyMap.html[`ReadOnlyMap`]
,
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html[`ReadWriteMap`]
or
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html[`WriteOnlyMap`]

[source,java]
----
include::code_examples/FunctionalMap.java[]
----

WARNING: At this stage, the Functional Map API is experimental and hence the
way FunctionalMap, ReadOnlyMap, WriteOnlyMap and ReadWriteMap are constructed
is temporary.

== Read-Only Map API

Read-only operations have the advantage that no locks are acquired
for the duration of the operation. Here's an example on how to the
equivalent operation for
link:{jdkdocroot}/java/util/Map.html#get-java.lang.Object-[Map.get(K)]:

[source,java]
----
include::code_examples/ReadOnlyMap.java[]
----

Read-only map also exposes operations to retrieve multiple keys in one go:

[source,java]
----
include::code_examples/ReadOnlyMapRetrieveKeys.java[]
----

Finally, read-only map also exposes methods to read all existing keys as well
as entries, which include both key and value information.

[[read_only_entry_view]]
=== Read-Only Entry View

The function parameters for read-only maps provide the user with a
link:{javadocroot}/org/infinispan/functional/EntryView.ReadEntryView.html[read-only entry view]
to interact with the data in the cache, which include these operations:

* link:{javadocroot}/org/infinispan/functional/EntryView.ReadEntryView.html#key()[`key()`]
method returns the key for which this function is being executed.
* link:{javadocroot}/org/infinispan/functional/EntryView.ReadEntryView.html#find()[`find()`]
returns a Java 8 `Optional` wrapping the value if present,
otherwise it returns an empty optional. Unless the value is guaranteed to
be associated with the key, it's recommended to use `find()` to verify
whether there's a value associated with the key.
* link:{javadocroot}/org/infinispan/functional/EntryView.ReadEntryView.html#get()[`get()`]
returns the value associated with the key. If the key has no value
associated with it, calling `get()` throws a `NoSuchElementException`.
`get()` can be considered as a shortcut of `ReadEntryView.find().get()`
which should be used only when the caller has guarantees that there's
definitely a value associated with the key.
* link:{javadocroot}/org/infinispan/functional/MetaParam.Lookup.html#findMetaParam(java.lang.Class)[`findMetaParam(Class<T> type)`]
allows metadata parameter information
associated with the cache entry to be looked up, for example: entry
lifespan, last  accessed time...etc.
See link:#meta_parameter[Metadata Parameter Handling] to find out more.

== Write-Only Map API

Write-only operations include operations that insert or update data in the
cache and also removals. Crucially, a write-only operation does not attempt
to read any previous value associated with the key. This is an important
optimization since that means neither the cluster nor any persistence stores
will be looked up to retrieve previous values. In the main {brandname} Cache,
this kind of optimization was achieved using a local-only per-invocation
flag, but the use case is so common that in this new functional API, this
optimization is provided as a first-class citizen.

Using
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html[write-only map API]
, an operation equivalent to
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java[`javax.cache.Cache` (`JCache`)]
's void returning
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java#L194[`put`]
can be achieved this way, followed by an attempt to read the stored
value using the read-only map API:

[source,java]
----
include::code_examples/WriteOnlyMap.java[]
----

Multiple key/value pairs can be stored in one go using
{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html#evalMany(java.util.Map,java.util.function.BiConsumer)[`evalMany`]
API:

[source,java]
----
include::code_examples/WriteOnlyMapStoreKeys.java[]
----

To remove all contents of the cache, there are two possibilities with
different semantics. If using
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html#evalAll(java.util.function.Consumer)[`evalAll`]
each cached entry is iterated over and the function is called
with that entry's information. Using this method also results in listeners being invoked.

[source,java]
----
include::code_examples/WriteOnlyMapRemoveAll.java[]
----

The alternative way to remove all entries is to call
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html#truncate()[`truncate`]
operation which clears the entire cache contents in one go without
invoking any listeners and is best-effort:

[source,java]
----
include::code_examples/WriteOnlyMapTruncate.java[]
----

[[write_only_entry_view]]
=== Write-Only Entry View
The function parameters for write-only maps provide the user with a
link:{javadocroot}/org/infinispan/functional/EntryView.WriteEntryView.html[write-only entry view]
to modify the data in the cache, which include these
operations:

* link:{javadocroot}/org/infinispan/functional/EntryView.WriteEntryView.html#set(V,org.infinispan.functional.MetaParam.Writable...)[`set(V, MetaParam.Writable...)`]
method allows for a new value to be
associated with the cache entry for which this function is executed, and it
optionally takes zero or more metadata parameters to be stored along with
the value. See link:#meta_parameter[Metadata Parameter Handling] for more information.
* link:{javadocroot}/org/infinispan/functional/EntryView.WriteEntryView.html#remove()[`remove()`]
method removes the cache entry, including both value and metadata
parameters associated with this key.

== Read-Write Map API

The final type of operations we have are read­write operations, and within
this category CAS-like (Compare­And­Swap) operations can be found.
This type of operations require previous value associated with the key
to be read and for locks to be acquired before executing the function.
The vast majority of operations within
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[`ConcurrentMap`]
and
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java[`JCache`]
APIs fall within this category, and they can easily be implemented using the
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html[read-write map API]
. Moreover, with
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html[read-write map API]
, you can make CAS­like comparisons not only based on value equality
but based on metadata parameter equality such as version information,
and you can send back previous value or boolean instances to signal
whether the CAS­like comparison succeeded.

Implementing a write operation that returns the previous value associated
with the cache entry is easy to achieve with the read-write map API:

[source,java]
----
include::code_examples/ReadWriteMap.java[]
----

link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html#replace-K-V-V-[`ConcurrentMap.replace(K, V, V)`]
is a replace function that compares the
value present in the map and if it's equals to the value passed in as
first parameter, the second value is stored, returning a boolean
indicating whether the replace was successfully completed. This operation
can easily be implemented using the read-write map API:

[source,java]
----
include::code_examples/ReadWriteMapReplace.java[]
----

NOTE: The function in the example above captures `oldValue` which is an
external value to the function which is valid use case.

Read-write map API contains `evalMany` and `evalAll` operations which behave
similar to the write-only map offerings, except that they enable previous
value and metadata parameters to be read.

[[read_write_entry_view]]
=== Read-Write Entry View
The function parameters for read-write maps provide the user with the
possibility to query the information associated with the key, including
value and metadata parameters, and the user can also use this
link:{javadocroot}/org/infinispan/functional/EntryView.ReadWriteEntryView.html[read-write entry view]
to modify the data in the cache.

The operations are exposed by read-write entry views are a union of
the operations exposed by link:#read_only_entry_view[read-only entry views]
and link:#write_only_entry_view[write-only entry views].

[[meta_parameter]]
== Metadata Parameter Handling
link:{javadocroot}/org/infinispan/functional/MetaParam.html[Metadata parameters]
provide extra information about the cache entry, such
as version information, lifespan, last accessed/used time...etc. Some of
these can be provided by the user, e.g. version, lifespan...etc, but some
others are computed internally and can only be queried, e.g. last
accessed/used time.

The functional map API provides a flexible way to store metadata parameters
along with an cache entry. To be able to store a metadata parameter, it must
extend
link:{javadocroot}/org/infinispan/functional/MetaParam.Lookup.html[`MetaParam.Writable`]
interface, and implement the methods to allow the
internal logic to extra the data. Storing is done via the
`set(V, MetaParam.Writable...)` method in the link:#write_only_entry_view[write-only entry view] or link:#read_write_entry_view[read-write entry view] function parameters.

Querying metadata parameters is available via the
link:{javadocroot}/org/infinispan/functional/MetaParam.Lookup.html#findMetaParam(java.lang.Class)[`findMetaParam(Class)`]
method
available via link:#read_write_entry_view[read-write entry view] or
link:#read_only_entry_view[read-only entry views] or function parameters.

Here is an example showing how to store metadata parameters and how to query
them:

[source,java]
----
include::code_examples/FunctionalMetaParam.java[]
----

If the metadata parameter is generic, for example
link:{javadocroot}/org/infinispan/functional/MetaParam.MetaEntryVersion.html[`MetaEntryVersion<T>`]
, retrieving the metadata parameter along with a specific type can be tricky
if using `.class` static helper in a class because it does not return a
`Class<T>` but only `Class`, and hence any generic information in the class is
lost:

[source,java]
----
include::code_examples/ReadOnlyMapMetaParam.java[]
----

When generic information is important the user can define a static helper
method that coerces the static class retrieval to the type requested,
and then use that helper method in the call to `findMetaParam`:

[source,java]
----
include::code_examples/ReadOnlyMapFindMetaParam.java[]
----

Finally, users are free to create new instances of metadata parameters to
suit their needs. They are stored and retrieved in the very same way as done
for the metadata parameters already provided by the functional map API.

[[_invocation_parameter]]
== Invocation Parameter
link:{javadocroot}/org/infinispan/functional/Param.html[Per-invocation parameters]
are applied to regular functional map API calls to
alter the behaviour of certain aspects. Adding per invocation parameters is
done using the
link:{javadocroot}/org/infinispan/functional/FunctionalMap.html#withParams(org.infinispan.functional.Param...)[`withParams(Param<?>...)`]
method.

link:{javadocroot}/org/infinispan/functional/Param.FutureMode.html[`Param.FutureMode`]
tweaks whether a method returning a
link:{jdkdocroot}/java/util/concurrent/CompletableFuture.html[`CompletableFuture`]
will span a thread to invoke the method, or instead will use the caller
thread. By default, whenever a call is made to a method returning a
link:{jdkdocroot}/java/util/concurrent/CompletableFuture.html[`CompletableFuture`]
, a separate thread will be span to execute the method asynchronously.
However, if the caller will immediately block waiting for the
link:{jdkdocroot}/java/util/concurrent/CompletableFuture.html[`CompletableFuture`]
to complete, spanning a different thread is wasteful, and hence
link:{javadocroot}/org/infinispan/functional/Param.FutureMode.html#COMPLETED[`Param.FutureMode.COMPLETED`]
can be passed as per-invocation parameter to avoid creating that extra thread. Example:

[source,java]
----
include::code_examples/ReadOnlyMapCompleted.java[]
----

Param.PersistenceMode controls whether a write operation will be propagated
to a persistence store. The default behaviour is for all write-operations
to be propagated to the persistence store if the cache is configured with
a persistence store. By passing PersistenceMode.SKIP as parameter,
the write operation skips the persistence store and its effects are only
seen in the in-memory contents of the cache. PersistenceMode.SKIP can
be used to implement an
link:{javadocroot}/org/infinispan/Cache.html#evict-K-[`Cache.evict()`]
method which removes data from memory but leaves the persistence store
untouched:

[source,java]
----
include::code_examples/WriteOnlyMapSkipPersistence.java[]
----

Note that there's no need for another PersistenceMode option to skip
reading from the persistence store, because a write operation can skip
reading previous value from the store by calling a write-only operation
via the WriteOnlyMap.

Finally, new Param implementations are normally provided by the functional
map API since they tweak how the internal logic works. So, for the most part
of users, they should limit themselves to using the Param instances exposed
by the API. The exception to this rule would be advanced users who decide
to add new interceptors to the internal stack. These users have the ability
to query these parameters within the interceptors.

[[functional_listeners]]
== Functional Listeners
The functional map offers a listener API, where clients can register for and
get notified when events take place. These notifications are post-event, so
that means the events are received after the event has happened.

The listeners that can be registered are split into two categories:
link:{javadocroot}/org/infinispan/functional/Listeners.WriteListeners.html[write listeners]
and
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.html[read-write listeners].

=== Write Listeners
link:{javadocroot}/org/infinispan/functional/Listeners.WriteListeners.html[Write listeners]
enable user to register listeners for any cache entry write events
that happen in either a read-write or write-only functional map.

Listeners for write events cannot distinguish between cache entry
created and cache entry modify/update events because they don't have
access to the previous value. All they know is that a new non-null
entry has been written.

However, write event listeners can distinguish between entry removals
and cache entry create/modify-update events because they can query
what the new entry's value via
link:{javadocroot}/org/infinispan/functional/EntryView.ReadEntryView.html#find()[`ReadEntryView.find()`]
method.

Adding a write listener is done via the WriteListeners interface
which is accessible via both
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html#listeners()[`ReadWriteMap.listeners()`]
and
link:{javadocroot}/org/infinispan/functional/FunctionalMap.WriteOnlyMap.html#listeners()[`WriteOnlyMap.listeners()`]
 method.

A write listener implementation can be defined either passing a function
to
link:{javadocroot}/org/infinispan/functional/Listeners.WriteListeners.html#onWrite(java.util.function.Consumer)[`onWrite(Consumer<ReadEntryView<K, V>>)`]
method, or passing a
WriteListener implementation to
link:{javadocroot}/org/infinispan/functional/Listeners.WriteListeners.html#add(org.infinispan.functional.Listeners.WriteListeners.WriteListener)[`add(WriteListener<K, V>)`]
method.
Either way, all these methods return an
link:{jdkdocroot}/java/lang/AutoCloseable.html[AutoCloseable]
instance that can be used to de-register the function listener:

[source,java]
----
include::code_examples/WriteOnlyMapWriteListener.java[]
----

=== Read-Write Listeners
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.html[Read-write listeners]
enable users to register listeners for cache entry created, modified
and removed events, and also register listeners for any cache entry
write events.

Entry created, modified and removed events can only be fired when these
originate on a read-write functional map, since this is the only one
that guarantees that the previous value has been read, and hence the
differentiation between create, modified and removed can be fully
guaranteed.

Adding a read-write listener is done via the
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.html[`ReadWriteListeners`]
interface which is accessible via
link:{javadocroot}/org/infinispan/functional/FunctionalMap.ReadWriteMap.html#listeners()[`ReadWriteMap.listeners()`]
method.

If interested in only one of the event types, the simplest way to add a
listener is to pass a function to either
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.ReadWriteListener.html#onCreate(java.util.function.Consumer)[`onCreate`]
,
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.ReadWriteListener.html#onModify(java.util.function.BiConsumer)[`onModify`]
or
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.ReadWriteListener.html#onRemove(java.util.function.Consumer)[`onRemove`]
methods. All these methods return an AutoCloseable instance that can be
used to de-register the function listener:

[source,java]
----
include::code_examples/ReadWriteMapAutoCloseable.java[]
----

If listening for two or more event types, it's better to pass in an
implementation of
link:{javadocroot}/org/infinispan/functional/Listeners.WriteListeners.WriteListener.html[`ReadWriteListener`]
interface via the
link:{javadocroot}/org/infinispan/functional/Listeners.ReadWriteListeners.html#add(org.infinispan.functional.Listeners.ReadWriteListeners.ReadWriteListener)[`ReadWriteListeners.add()`]
method. `ReadWriteListener` offers the same `onCreate`/`onModify`/`onRemove`
callbacks with default method implementations that are empty:

[source,java]
----
include::code_examples/ReadWriteMapListener.java[]
----

== Marshalling of Functions
Running functional map in a cluster of nodes involves marshalling and
replication of the operation parameters under certain circumstances.

To be more precise, when write operations are executed in a cluster,
regardless of read-write or write-only operations, all the parameters
to the method and the functions are replicated to other nodes.

There are multiple ways in which a function can be marshalled. The simplest
way, which is also the most costly option in terms of payload size, is
to mark the function as
link:{jdkdocroot}/java/io/Serializable.html[`Serializable`]:

[source,java]
----
include::code_examples/WriteOnlyMapSerializable.java[]
----

{brandname} provides overloads for all functional methods that make lambdas
passed directly to the API serializable by default; the compiler automatically selects
this overload if that's possible. Therefore you can call

[source,java]
----
include::code_examples/WriteOnlyMapWriteFuture.java[]
----

without doing the cast described above.

A more economical way to marshall a function is to provide an {brandname}
link:{javadocroot}/org/infinispan/commons/marshall/Externalizer.html[`Externalizer`] for it:

[source,java]
----
include::code_examples/WriteOnlyMapExternalizer.java[]
----

To help users take advantage of the tiny payloads generated by
`Externalizer`-based functions, the functional API comes with a helper
class called
link:{javadocroot}/org/infinispan/commons/marshall/MarshallableFunctions.html[`org.infinispan.commons.marshall.MarshallableFunctions`]
which provides marshallable functions for some of the most commonly user
functions.

In fact, all the functions required to implement
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[`ConcurrentMap`]
and
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java[`JCache`]
using the functional map API have been defined in
link:{javadocroot}/org/infinispan/commons/marshall/MarshallableFunctions.html[`MarshallableFunctions`].
For example, here is an implementation of JCache's
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java#L283[`boolean putIfAbsent(K, V)`]
using functional map API which can be run in a cluster:

[source,java]
----
include::code_examples/ReadWriteMapMarshallableFunctions.java[]
----

== Use Cases for Functional API

This new API is meant to complement existing Key/Value {brandname} API
offerings, so you'll still be able to use
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[`ConcurrentMap`]
or
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java[`JCache`]
standard APIs if that's what suits your use case best.

The target audience for this new API is either:

* Distributed or persistent caching/in­memory­data­grid users that want
to benefit from CompletableFuture and/or Traversable for async/lazy data
grid or caching data manipulation. The clear advantage here is that threads
do not need to be idle waiting for remote operations to complete, but
instead these can be notified when remote operations complete and then
chain them with other subsequent operations.
* Users who want to go beyond the standard operations exposed by
link:{jdkdocroot}/java/util/concurrent/ConcurrentMap.html[`ConcurrentMap`]
and
link:https://github.com/jsr107/jsr107spec/blob/v1.0.0/src/main/java/javax/cache/Cache.java[`JCache`], for example, if you want to do a replace
operation using metadata parameter equality instead of value equality, or
if you want to retrieve metadata information from values and so on.
