1 package com.atlassian.vcache;
2
3 import com.atlassian.annotations.PublicApi;
4
5 import java.time.Duration;
6 import java.util.Optional;
7
8 import static java.util.Objects.requireNonNull;
9
10 /**
11 * Builder for creating {@link ExternalCacheSettings} instances.
12 *
13 * @since 1.0
14 */
15 @PublicApi
16 public class ExternalCacheSettingsBuilder {
17 private Optional<Duration> defaultTtl = Optional.empty();
18 private Optional<Integer> entryCountHint = Optional.empty();
19 private Optional<ChangeRate> dataChangeRateHint = Optional.empty();
20 private Optional<ChangeRate> entryGrowthRateHint = Optional.empty();
21
22 /**
23 * Creates an instance with no settings initialised.
24 */
25 public ExternalCacheSettingsBuilder() {
26 }
27
28 /**
29 * Constructs an instance initialised with the supplied settings.
30 *
31 * @param settings the settings to configure the instance with.
32 */
33 public ExternalCacheSettingsBuilder(ExternalCacheSettings settings) {
34 this.defaultTtl = requireNonNull(settings.getDefaultTtl());
35 this.entryCountHint = requireNonNull(settings.getEntryCountHint());
36 this.dataChangeRateHint = requireNonNull(settings.getDataChangeRateHint());
37 this.entryGrowthRateHint = requireNonNull(settings.getEntryGrowthRateHint());
38 }
39
40 /**
41 * Returns a new {@link ExternalCacheSettings} instance configured using the supplied settings.
42 *
43 * @return a new {@link ExternalCacheSettings} instance configured using the supplied settings.
44 */
45 public ExternalCacheSettings build() {
46 return new ExternalCacheSettings(
47 defaultTtl, entryCountHint, dataChangeRateHint, entryGrowthRateHint);
48 }
49
50 /**
51 * Specifies the default time-to-live for entries to be held in the cache and must be a positive number.
52 * The time-to-live is calculated on the time the entry was added or updated.
53 *
54 * @param ttl the default time-to-live for entries to be held in the cache
55 * @return the builder
56 * @throws IllegalArgumentException thrown if <tt>ttl</tt> is not positive
57 */
58 public ExternalCacheSettingsBuilder defaultTtl(Duration ttl) {
59 if (ttl.isNegative() || ttl.isZero()) {
60 throw new IllegalArgumentException("ttl must be greater than zero, passed: " + ttl);
61 }
62
63 defaultTtl = Optional.of(ttl);
64 return this;
65 }
66
67 /**
68 * Provides a hint on the expected number of entries to be held in the cache. Must not be a negative number.
69 * The implementation is free to decide how to interpret <tt>0</tt>. For example, it may decide to still cache
70 * values externally, or it may decide to not store entries in the cache.
71 *
72 * @param hint the expected number of entries to be held in the cache
73 * @return the builder
74 * @throws IllegalArgumentException thrown if <tt>hint</tt> is negative
75 */
76 public ExternalCacheSettingsBuilder entryCountHint(int hint) {
77 if (hint < 0) {
78 throw new IllegalArgumentException("maxEntries cannot be negative, passed: " + hint);
79 }
80
81 entryCountHint = Optional.of(hint);
82 return this;
83 }
84
85 /**
86 * Provides a hint on the expected change rate for data updates.
87 *
88 * @param hint the expected change rate for data updates.
89 * @return the builder
90 */
91 public ExternalCacheSettingsBuilder dataChangeRateHint(ChangeRate hint) {
92 dataChangeRateHint = Optional.of(hint);
93 return this;
94 }
95
96 /**
97 * Provides a hint on the expected change rate for entry additions.
98 *
99 * @param hint the expected change rate for entry additions.
100 * @return the builder
101 */
102 public ExternalCacheSettingsBuilder entryGrowthRateHint(ChangeRate hint) {
103 entryGrowthRateHint = Optional.of(hint);
104 return this;
105 }
106 }