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
24 /**
25 * @return a new {@link CacheSettings} instance with
26 */
27 @Nonnull
28 public CacheSettings build()
29 {
30 return new DefaultCacheSettings(expireAfterAccess, expireAfterWrite, flushable,
31 local, maxEntries, replicateAsynchronously, replicateViaCopy);
32 }
33
34 /**
35 * Set a hint for the cache regarding how long entries should be held in the cache.
36 * @param expireAfter Time to retain entries for since their last access.
37 * @param timeUnit The {@link TimeUnit} for the time
38 * @return this builder
39 */
40 @Nonnull
41 public CacheSettingsBuilder expireAfterAccess(long expireAfter, @Nonnull TimeUnit timeUnit)
42 {
43 this.expireAfterAccess = timeUnit.toMillis(expireAfter);
44 return this;
45 }
46
47 /**
48 * Set a hint for the cache regarding how long entries should be held in the cache.
49 * @param expireAfter Time to retain entries from when they were created.
50 * @param timeUnit The {@link TimeUnit} for the time
51 * @return this builder
52 */
53 @Nonnull
54 public CacheSettingsBuilder expireAfterWrite(long expireAfter, @Nonnull TimeUnit timeUnit)
55 {
56 this.expireAfterWrite = timeUnit.toMillis(expireAfter);
57 return this;
58 }
59
60 /**
61 * Indicates that this cache can be flushed by the cache manager when desired.
62 * @return this builder
63 */
64 @Nonnull
65 public CacheSettingsBuilder flushable()
66 {
67 this.flushable = true;
68 return this;
69 }
70
71 /**
72 * Indicates that this cache cannot be flushed by the cache manager when desired.
73 * @return this builder
74 */
75 @Nonnull
76 public CacheSettingsBuilder unflushable()
77 {
78 this.flushable = false;
79 return this;
80 }
81
82 /**
83 * Indicates that this cache can have a maximum number of entries.
84 * @param maxEntries The maximum number of entries. Must be greater than zero.
85 * @return this builder
86 */
87 @Nonnull
88 public CacheSettingsBuilder maxEntries(int maxEntries)
89 {
90 if (0 >= maxEntries)
91 {
92 throw new IllegalArgumentException("maxEntries must be greater than zero, passed: " + maxEntries);
93 }
94 this.maxEntries = maxEntries;
95 return this;
96 }
97
98 /**
99 * Indicates that in a clustered environment with replicated caches, this
100 * cache should replicate asynchronously. By default, it is up to the host
101 * application as to whether replication is synchronous or asynchronous.
102 *
103 * <br/>
104 * When it is synchronous, cache mutations block on the originating node until
105 * all nodes in the cluster have replicated the mutation. Asynchronous
106 * replication provides greater responsiveness at the expense of
107 * consistency.
108 *
109 * @return this builder
110 */
111 @Nonnull
112 public CacheSettingsBuilder replicateAsynchronously()
113 {
114 this.replicateAsynchronously = true;
115 return this;
116 }
117
118 /**
119 * Indicates that in a clustered environment with replicated caches, this
120 * cache should replicate synchronously.
121 *
122 * @return this builder
123 * @see #replicateAsynchronously
124 * @since 2.3.0
125 */
126 @Nonnull
127 public CacheSettingsBuilder replicateSynchronously()
128 {
129 this.replicateAsynchronously = false;
130 return this;
131 }
132
133 /**
134 * Indicates that in a clustered environment with replicated caches, this
135 * cache should replicate put and update operations by copying the relevant
136 * key and value across the wire (requiring both of them to be {@link
137 * java.io.Serializable}).
138 * <br/>
139 * By default, it is up to the host application as to whether replication is via
140 * copy or invalidation.
141 *
142 * @return this builder
143 * @see #replicateViaInvalidation()
144 */
145 @Nonnull
146 public CacheSettingsBuilder replicateViaCopy()
147 {
148 this.replicateViaCopy = true;
149 return this;
150 }
151
152 /**
153 * Indicates that in a clustered environment with replicated caches, this
154 * cache should replicate by sending only the key across the wire, for invalidation by
155 * the other nodes in the cluster; this requires only the key to be {@link
156 * java.io.Serializable}.
157 * <br/>
158 * By default, it is up to the host application as to whether replication is via
159 * copy or invalidation.
160 *
161 * @return this builder
162 * @see #replicateViaCopy
163 * @since 2.3.0
164 */
165 @Nonnull
166 public CacheSettingsBuilder replicateViaInvalidation()
167 {
168 this.replicateViaCopy = false;
169 return this;
170 }
171
172 /**
173 * Indicates that this cache should be local to the node (JVM) where the cache is created.
174 * By default, caches will be clustered in a clustered deployment.
175 * @return this builder
176 */
177 @Nonnull
178 public CacheSettingsBuilder local()
179 {
180 this.local = true;
181 return this;
182 }
183
184 /**
185 * Indicates that this cache should be clustered in a clustered deployment.
186 * @return this builder
187 */
188 @Nonnull
189 public CacheSettingsBuilder remote()
190 {
191 this.local = false;
192 return this;
193 }
194 }