Garbage collector and related settings

Either one of the following garbage collectors must be used:

Garbage-First (G1) Collector (-XX:+UseG1GC)
Concurrent garbage collector (-XX:+UseConcMarkSweepGC)

For clarity, set one of these explicitly by the given option, since the default, which is determined by the Java version, can change. G1 is the recommended option. Only use the concurrent garbage collector when you plan to allocate larger memory blocks.

Heap memory threshold for file buffering (inMemoryThreshold)

This memory threshold setting is only relevant if an ImageMaster extension executes further processing on a revision object. This is the case, for example, if you use the Signature Service, which needs to access a revision object (a file to be archived) multiple times to calculate a hash digest.

If you are not using the Signature Service and you are not aware of any customer extension that requires special processing of revision objects, you can just leave the default setting and ignore all explanations below, which illustrate how to find an optimized value for this setting.

In a use case where this memory threshold is relevant, the maximum memory size for buffering temporary file data in the heap can be adjusted via the option “inMemoryThreshold” on the application server. If this size is exceeded, a temporary file is created in the temporary realm, which can be set up via the AdminClient. This temporary file is always automatically cleaned up, when it is not needed anymore.

Two settings determine the memory threshold in byte, where the second one applies only in case of single instancing:

standard use case – default 65536 byte (64 KiB):
```
ima.archive.tempFile.inMemoryThreshold.std
```
single instancing – default 131072 byte (128 KiB):
```
ima.archive.tempFile.inMemoryThreshold.singleInst
```

The following rule of thumb can be used to determine an appropriate value for these thresholds. Deviating recommendations may apply in addition, depending on individual project needs and scenarios:

inMemoryThreshold = HeapSizeres ÷ Requestsmax÷ Attachmentsmax
HeapSizeres	Memory size planned to be reserved for buffering in the heap Performance is likely to increase with more size at the cost of heap memory consumption because less intermediate files have to be written to the temporary storage location.
Requestsmax	Maximum number of expected parallel requests This refers to requests which create or update documents used by the Signature Service or some custom extension.
Attachmentsmax	Maximum number of expected document attachments in one request This refers to file attachments of an ImageMaster document.
Table 309: Rule of thumb for file buffering size adjustment

The following table provides a rule of thumb to decide, which garbage collector to use depending on the totally available heap size and the intended inMemoryThreshold. First choose the row which indicates your available heap size, then check the limit given for inMemoryThreshold:

If you are within the given limit, and your inMemoryThreshold is lower than the listed one, choose the G1 collector.
If you exceed the listed inMemoryThreshold, choose the concurrent garbage collector instead.

Total heap size available in GiB	If inMemoryThreshold in MiB is lower than the listed value, choose G1
< 4	< 0,5
4 - 8	< 1
8 - 16	< 2
16 - 32	< 4
32 - 64	< 8
> 64	< 32
Table 310: Rule of thumb for criteria when to use the concurrent garbage collector instead of G1

Example 1 – calculating a recommended threshold based on a usage scenario

If you know your expected maximum number of parallel requests (e.g. 8) and attachments (e.g. 2) and want to reserve a given amount of heap, for example 128 MB for buffering, use the formula to calculate the threshold:

inMemoryThreshold = HeapSizeres ÷ Requestsmax÷ Attachmentsmax =

= 256 MB ÷ 8 ÷ 2 = 16 MB

This effectively means if file sizes are lower than 16 MB and the conditions apply (max 8 parallel requests and 2 attachments), the files can be handled completely in the heap so no temporary file has to be written in the temporary archive realm.

Let’s assume your totally available heap space is 24 GiB, then you can see from the table above that you exceed the limit of 4 MiB and should therefore use the concurrent garbage collector (instead of G1).

Example 2 – looking at an increased value and its implications

The default value for this threshold (inMemoryThreshold) is 64 KiB. If you want to handle larger files in memory (e.g. 600 KB) and expect more requests in parallel (e.g. 40) and more attachments (e.g. 2), you can plan to use more memory in the heap:

HeapSizeres = inMemoryThreshold ✕ Requestsmax ✕ Attachmentsmax = 600 KB ✕ 40 ✕ 2 = 48 MB

If you cannot afford to use more heap memory but can accept some performance reduction, you can set a lower threshold (e.g. 300 KB):

HeapSizeres = inMemoryThreshold ✕ Requestsmax ✕ Attachmentsmax = 300 KB ✕ 40 ✕ 2 = 24 MB

Topics related to heap management in this manual

For options relating to the heap size also see Memory management in table Memory management and auto recover.