1 package com.atlassian.vcache.internal;
2
3 import java.util.function.Function;
4 import javax.annotation.Nonnull;
5
6 import com.atlassian.vcache.ExternalCacheSettings;
7 import com.atlassian.vcache.JvmCacheSettings;
8
9 /**
10 * The lifecyle management interface that contains methods that need to be called, by the
11 * host application, at different stages.
12 *
13 * <p>
14 * Handlers need to be provided to {@link #applicationSetup(String, Function, Function)}. These handlers
15 * are called whenever a cache is about to be configured by the VCache implementation. Using these hooks, the
16 * host application can:
17 * </p>
18 * <ul>
19 * <li>
20 * Override the current cache settings. For example, enforcing an application wide
21 * maximum time-to-live.
22 * </li>
23 * <li>
24 * Log a warning (or whatever) based on it's policy (e.g. an unknown {@link com.atlassian.vcache.JvmCache}
25 * is being created.
26 * </li>
27 * <li>
28 * Prevent a cache from being created, based on it's policy, by throwing a {@link RuntimeException}. The
29 * VCache implementation will propagate these exceptions to the original caller.
30 * </li>
31 * </ul>
32 *
33 * @since 1.0
34 */
35 public interface VCacheLifecycleManager
36 {
37 /**
38 * To be called when the host application is being setup. It should only be called once.
39 *
40 * @throws IllegalStateException if this method is called multiple times.
41 */
42 void applicationSetup(
43 String productIdentifier,
44 Function<JvmCacheDetails, JvmCacheSettings> jvmCacheCreationHandler,
45 Function<ExternalCacheDetails, ExternalCacheSettings> externalCacheCreationHandler);
46
47 /**
48 * To be called when the host application is being shutdown. This method will block
49 * until there are more executing requests, before shutting down. This method should only
50 * be called once. If the caller does not want to block, then call {@link #currentRequestCount()}
51 * beforehand to check whether any requests are currently in progress.
52 */
53 void applicationTeardown();
54
55 /**
56 * Returns the current number of requests in progress.
57 * @return the current number of requests in progress.
58 */
59 int currentRequestCount();
60
61 /**
62 * Returns whether a request is currently in progress for this thread.
63 * @return whether a request is currently in progress for this thread.
64 */
65 boolean isRequestInProgress();
66
67 /**
68 * To be called after a thread has performed a request (unit of work). Duplicate calls are ignored (a warning
69 * may be logged by the implementation).
70 *
71 * @return the cache metrics for the request
72 */
73 @Nonnull
74 CacheMetrics requestTeardown();
75 }