1 package com.atlassian.cache;
2
3 import java.util.concurrent.TimeUnit;
4
5 import javax.annotation.Nonnull;
6
7 import com.atlassian.annotations.PublicApi;
8
9 /**
10 * A builder for creating {@link CacheSettings} instances.
11 * @since 2.0
12 */
13 @PublicApi
14 public class CacheSettingsBuilder
15 {
16 private Long expireAfterAccess;
17 private Long expireAfterWrite;
18 private Boolean flushable;
19 private Boolean local;
20 private Integer maxEntries;
21 private Boolean replicateAsynchronously;
22 private Boolean replicateViaCopy;
23 private Boolean statisticsEnabled;
24
25 /**
26 * Constructor
27 */
28 public CacheSettingsBuilder()
29 {
30 }
31
32 /**
33 * Constructor that initializes the builder with the settings from a {@link CacheSettings} instance
34 *
35 * @param settings the instance to initialize the builder with
36 */
37 public CacheSettingsBuilder(CacheSettings settings)
38 {
39 this.expireAfterAccess = settings.getExpireAfterAccess();
40 this.expireAfterWrite = settings.getExpireAfterWrite();
41 this.flushable = settings.getFlushable();
42 this.local = settings.getLocal();
43 this.maxEntries = settings.getMaxEntries();
44 this.replicateAsynchronously = settings.getReplicateAsynchronously();
45 this.replicateViaCopy = settings.getReplicateViaCopy();
46 this.statisticsEnabled = settings.getStatisticsEnabled();
47 }
48
49 /**
50 * @return a new {@link CacheSettings} instance with
51 */
52 @Nonnull
53 public CacheSettings build()
54 {
55 return new DefaultCacheSettings(expireAfterAccess, expireAfterWrite, flushable,
56 local, maxEntries, replicateAsynchronously, replicateViaCopy, statisticsEnabled);
57 }
58
59 /**
60 * Set a hint for the cache regarding how long entries should be held in the cache.
61 * @param expireAfter Time to retain entries for since their last access.
62 * @param timeUnit The {@link TimeUnit} for the time
63 * @return this builder
64 */
65 @Nonnull
66 public CacheSettingsBuilder expireAfterAccess(long expireAfter, @Nonnull TimeUnit timeUnit)
67 {
68 this.expireAfterAccess = timeUnit.toMillis(expireAfter);
69 return this;
70 }
71
72 /**
73 * Set a hint for the cache regarding how long entries should be held in the cache.
74 * @param expireAfter Time to retain entries from when they were created.
75 * @param timeUnit The {@link TimeUnit} for the time
76 * @return this builder
77 */
78 @Nonnull
79 public CacheSettingsBuilder expireAfterWrite(long expireAfter, @Nonnull TimeUnit timeUnit)
80 {
81 this.expireAfterWrite = timeUnit.toMillis(expireAfter);
82 return this;
83 }
84
85 /**
86 * Indicates that this cache can be flushed by the cache manager when desired.
87 * @return this builder
88 */
89 @Nonnull
90 public CacheSettingsBuilder flushable()
91 {
92 this.flushable = true;
93 return this;
94 }
95
96 /**
97 * Indicates that this cache cannot be flushed by the cache manager when desired.
98 * @return this builder
99 */
100 @Nonnull
101 public CacheSettingsBuilder unflushable()
102 {
103 this.flushable = false;
104 return this;
105 }
106
107 /**
108 * Indicates that this cache can have a maximum number of entries.
109 * @param maxEntries The maximum number of entries. Must be greater than zero.
110 * @return this builder
111 */
112 @Nonnull
113 public CacheSettingsBuilder maxEntries(int maxEntries)
114 {
115 if (0 >= maxEntries)
116 {
117 throw new IllegalArgumentException("maxEntries must be greater than zero, passed: " + maxEntries);
118 }
119 this.maxEntries = maxEntries;
120 return this;
121 }
122
123 /**
124 * Indicates that in a clustered environment with replicated caches, this
125 * cache should replicate asynchronously. By default, it is up to the host
126 * application as to whether replication is synchronous or asynchronous.
127 *
128 * <br>
129 * When it is synchronous, cache mutations block on the originating node until
130 * all nodes in the cluster have replicated the mutation. Asynchronous
131 * replication provides greater responsiveness at the expense of
132 * consistency.
133 *
134 * @return this builder
135 */
136 @Nonnull
137 public CacheSettingsBuilder replicateAsynchronously()
138 {
139 this.replicateAsynchronously = true;
140 return this;
141 }
142
143 /**
144 * Indicates that in a clustered environment with replicated caches, this
145 * cache should replicate synchronously.
146 *
147 * @return this builder
148 * @see #replicateAsynchronously
149 * @since 2.3.0
150 */
151 @Nonnull
152 public CacheSettingsBuilder replicateSynchronously()
153 {
154 this.replicateAsynchronously = false;
155 return this;
156 }
157
158 /**
159 * Indicates that in a clustered environment with replicated caches, this
160 * cache should replicate put and update operations by copying the relevant
161 * key and value across the wire (requiring both of them to be {@link
162 * java.io.Serializable}).
163 * <br>
164 * By default, it is up to the host application as to whether replication is via
165 * copy or invalidation.
166 *
167 * @return this builder
168 * @see #replicateViaInvalidation()
169 */
170 @Nonnull
171 public CacheSettingsBuilder replicateViaCopy()
172 {
173 this.replicateViaCopy = true;
174 return this;
175 }
176
177 /**
178 * Indicates that in a clustered environment with replicated caches, this
179 * cache should replicate by sending only the key across the wire, for invalidation by
180 * the other nodes in the cluster; this requires only the key to be {@link
181 * java.io.Serializable}.
182 * <br>
183 * By default, it is up to the host application as to whether replication is via
184 * copy or invalidation.
185 *
186 * @return this builder
187 * @see #replicateViaCopy
188 * @since 2.3.0
189 */
190 @Nonnull
191 public CacheSettingsBuilder replicateViaInvalidation()
192 {
193 this.replicateViaCopy = false;
194 return this;
195 }
196
197 /**
198 * Indicates that this cache should be local to the node (JVM) where the cache is created.
199 * By default, caches will be clustered in a clustered deployment.
200 * @return this builder
201 */
202 @Nonnull
203 public CacheSettingsBuilder local()
204 {
205 this.local = true;
206 return this;
207 }
208
209 /**
210 * Indicates that this cache should be clustered in a clustered deployment.
211 * @return this builder
212 */
213 @Nonnull
214 public CacheSettingsBuilder remote()
215 {
216 this.local = false;
217 return this;
218 }
219
220 /**
221 * Indicates that this cache should record statistics.
222 * @return this builder
223 */
224 public CacheSettingsBuilder statisticsEnabled()
225 {
226 this.statisticsEnabled = true;
227 return this;
228 }
229
230 /**
231 * Indicates that this cache should not record statistics.
232 * @return this builder
233 */
234 public CacheSettingsBuilder statisticsDisabled()
235 {
236 this.statisticsEnabled = false;
237 return this;
238 }
239 }