|
@@ -25,49 +25,110 @@ package uk.co.md87.evetool.api.io;
|
25
|
25
|
import java.util.Map;
|
26
|
26
|
|
27
|
27
|
/**
|
|
28
|
+ * Provides methods of accessing and updating a cache for API requests.
|
28
|
29
|
*
|
29
|
|
- * TODO: Document ApiCache
|
30
|
30
|
* @author chris
|
31
|
31
|
*/
|
32
|
32
|
public interface ApiCache {
|
33
|
33
|
|
|
34
|
+ /**
|
|
35
|
+ * Describes the status of a cache request.
|
|
36
|
+ */
|
34
|
37
|
public static enum CacheStatus {
|
|
38
|
+ /** The request missed (no cached result). */
|
35
|
39
|
MISS,
|
|
40
|
+ /** The request hit but the cached entry has expired. */
|
36
|
41
|
EXPIRED,
|
|
42
|
+ /** The request hit successfully. */
|
37
|
43
|
HIT;
|
38
|
44
|
}
|
39
|
45
|
|
|
46
|
+ /**
|
|
47
|
+ * Represents the result of a cache request.
|
|
48
|
+ */
|
40
|
49
|
public static class CacheResult {
|
41
|
50
|
|
|
51
|
+ /** The actual cached data. */
|
42
|
52
|
private final String data;
|
|
53
|
+
|
|
54
|
+ /** The time the data was cached at (milliseconds since the epoch). */
|
43
|
55
|
private final long cachedAt;
|
|
56
|
+
|
|
57
|
+ /** The time the data was cached until (milliseconds since the epoch). */
|
44
|
58
|
private final long cachedUntil;
|
45
|
59
|
|
46
|
|
- public CacheResult(String data, long cachedAt, long cachedUntil) {
|
|
60
|
+ /**
|
|
61
|
+ * Creates a new CacheResult object.
|
|
62
|
+ *
|
|
63
|
+ * @param data The cache data being returned
|
|
64
|
+ * @param cachedAt The time at which the data was cached
|
|
65
|
+ * @param cachedUntil The time at which the data will expire
|
|
66
|
+ */
|
|
67
|
+ public CacheResult(final String data, final long cachedAt, final long cachedUntil) {
|
47
|
68
|
this.data = data;
|
48
|
69
|
this.cachedAt = cachedAt;
|
49
|
70
|
this.cachedUntil = cachedUntil;
|
50
|
71
|
}
|
51
|
72
|
|
|
73
|
+ /**
|
|
74
|
+ * Retrieves the time that the data was cached at.
|
|
75
|
+ *
|
|
76
|
+ * @return This result's cached-at time
|
|
77
|
+ */
|
52
|
78
|
public long getCachedAt() {
|
53
|
79
|
return cachedAt;
|
54
|
80
|
}
|
55
|
81
|
|
|
82
|
+ /**
|
|
83
|
+ * Retrieves the time that the data is cached until.
|
|
84
|
+ *
|
|
85
|
+ * @return This result's cached-until time
|
|
86
|
+ */
|
56
|
87
|
public long getCachedUntil() {
|
57
|
88
|
return cachedUntil;
|
58
|
89
|
}
|
59
|
90
|
|
|
91
|
+ /**
|
|
92
|
+ * Retrieves the response to this request.
|
|
93
|
+ *
|
|
94
|
+ * @return The data previously stored in the cache
|
|
95
|
+ */
|
60
|
96
|
public String getData() {
|
61
|
97
|
return data;
|
62
|
98
|
}
|
63
|
99
|
|
64
|
100
|
}
|
65
|
101
|
|
|
102
|
+ /**
|
|
103
|
+ * Updates the cache for the specified request to contain the specified
|
|
104
|
+ * data until the specified time.
|
|
105
|
+ *
|
|
106
|
+ * @param method The API method being requested
|
|
107
|
+ * @param args The arguments passed to that method
|
|
108
|
+ * @param data The data that has been returned
|
|
109
|
+ * @param cacheUntil The time (milliseconds since the epoch) to cache until
|
|
110
|
+ */
|
66
|
111
|
void setCache(final String method, final Map<String, String> args,
|
67
|
112
|
final String data, final long cacheUntil);
|
68
|
113
|
|
|
114
|
+ /**
|
|
115
|
+ * Checks the cache status of the specified request.
|
|
116
|
+ *
|
|
117
|
+ * @param method The API method that is being checked
|
|
118
|
+ * @param args The arguments that will be passed to that method
|
|
119
|
+ * @return A {@link CacheStatus} object describing the status of the cache
|
|
120
|
+ */
|
69
|
121
|
CacheStatus getCacheStatus(final String method, final Map<String, String> args);
|
70
|
122
|
|
|
123
|
+ /**
|
|
124
|
+ * Retrieves a cached API query. This method assumes that the cache has
|
|
125
|
+ * previously been verified to contain the specified entry; if the cache
|
|
126
|
+ * does not contain the entry, the behaviour of this method is undefined.
|
|
127
|
+ *
|
|
128
|
+ * @param method The API method requested
|
|
129
|
+ * @param args Any arguments passed to that method
|
|
130
|
+ * @return A {@link CacheResult} object describing the resulting data
|
|
131
|
+ */
|
71
|
132
|
CacheResult getCache(final String method, final Map<String, String> args);
|
72
|
133
|
|
73
|
134
|
}
|