[[sfs_cache_store]]
==== Single File Store

The single file cache store keeps all data in a single file. The way it
looks up data is by keeping an in-memory index of keys and the positions of
their values in this file. This results in greater performance compared to old
file cache store. There is one caveat though. Since the single file based
cache store keeps keys in memory, it can lead to increased memory consumption,
and hence it's not recommended for caches with big keys.

In certain use cases, this cache store suffers from fragmentation: if you
store larger and larger values, the space is not reused and instead the entry
is appended at the end of the file. The space (now empty) is reused only if you
write another entry that can fit there. Also, when you remove all entries from
the cache, the file won't shrink, and neither will be de-fragmented.

These are the available configuration options for the single file cache store:

* `path` is the file-system location where {brandname} stores data.
+
For embedded deployments, {brandname} stores data to the current working
directory. To store data in a different location, specify the absolute path to
that directory as the value.
+
For server deployments, {brandname} stores data in
ifndef::productized[]
`$ISPN_HOME/data`.
endif::productized[]
ifdef::productized[]
`$RHDG_HOME/data`.
endif::productized[]
You should not change the default location for {brandname} server. In other
words, do not set a value for `path` with server deployments.

you should create a path declaration and
use the `relative-to` attribute for the file store location. If you set
`relative-to` to a directory location or environment variable, {brandname}
server startup fails.

* `max-entries` specifies the maximum number of entries to keep in this file
store. As mentioned before, in order to speed up lookups, the single file
cache store keeps an index of keys and their corresponding position in the
file. To avoid this index resulting in memory consumption problems, this
cache store can bounded by a maximum number of entries that it stores. If
this limit is exceeded, entries are removed permanently using the LRU
algorithm both from  the in-memory index and the underlying file based
cache store. So, setting a maximum limit only makes sense when {brandname} is
used as a cache, whose contents can be recomputed or they can be retrieved
from the authoritative data store. If this maximum limit is set when the
{brandname} is used as an authoritative data store, it could lead to data
loss, and hence it's not recommended for this use case. The default value is
`-1` which means that the file store size is unlimited.

//Exclude segmentation support from productized docs.
ifndef::productized[]
===== Segmentation support
The single file cache store supports segmentation and creates a separate
instance per segment. Segmentation results in multiple directories under the
configured directory, where each directory is a number that represents the
segment to which the data maps.
endif::productized[]

===== Declarative Configuration
The following examples show declarative configuration for a single file cache
store.

.Library Mode

[source,xml,options=nowrap]
----
<persistence>
   <file-store path="/tmp/myDataStore" max-entries="5000"/>
</persistence>
----

.Server Mode

[source,xml,options=nowrap]
----
<persistence>
   <file-store max-entries="5000"/>
</persistence>
----

===== Programmatic Configuration
The following example shows programmatic configuration for a single file cache store:

[source,java,options=nowrap]
----
ConfigurationBuilder b = new ConfigurationBuilder();
b.persistence()
    .addSingleFileStore()
    .location("/tmp/myDataStore")
    .maxEntries(5000);
----
