[id='remotecache_api']
= RemoteCache API

The collection methods `keySet`, `entrySet` and `values` are backed by the
remote cache. That is that every method is called back into the `RemoteCache`.
This is useful as it allows for the various keys, entries or values to be
retrieved lazily, and not requiring them all be stored in the client memory at
once if the user does not want.

These collections adhere to the `Map` specification being that `add` and
`addAll` are not supported but all other methods are supported.

One thing to note is the `Iterator.remove` and `Set.remove` or
`Collection.remove` methods require more than 1 round trip to the server to
operate. You can check out the
link:{javadocroot}/org/infinispan/client/hotrod/RemoteCache.html[RemoteCache]
Javadoc to see more details about these and the other methods.

.Iterator Usage

The iterator method of these collections uses `retrieveEntries` internally,
which is described below. If you notice `retrieveEntries` takes an argument for
the batch size. There is no way to provide this to the iterator. As such the
batch size can be configured via system property
`infinispan.client.hotrod.batch_size` or through the link:{javadocroot}/org/infinispan/client/hotrod/configuration/ConfigurationBuilder.html#batchSize-int-[ConfigurationBuilder] when configuring the
`RemoteCacheManager`.

Also the `retrieveEntries` iterator returned is `Closeable` as such the
iterators from `keySet`, `entrySet` and `values` return an `AutoCloseable`
variant. Therefore you should always close these `Iterator`s when you are done
with them.

[source,java]
----
try (CloseableIterator<Map.Entry<K, V>> iterator = remoteCache.entrySet().iterator()) {

      }
----

*What if I want a deep copy and not a backing collection?*

Previous version of `RemoteCache` allowed for the retrieval of a deep copy
of the `keySet`. This is still possible with the new backing map, you just
have to copy the contents yourself. Also you can do this with `entrySet` and
`values`, which we didn't support before.

[source,java]
----
Set<K> keysCopy = remoteCache.keySet().stream().collect(Collectors.toSet());
----
