generated from oracle/template-repo
-
Notifications
You must be signed in to change notification settings - Fork 3
/
cache.go
254 lines (203 loc) · 12.7 KB
/
cache.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
/*
* Copyright (c) 2022, 2024 Oracle and/or its affiliates.
* Licensed under the Universal Permissive License v 1.0 as shown at
* https://oss.oracle.com/licenses/upl.
*/
package coherence
import (
"context"
"github.com/oracle/coherence-go-client/coherence/filters"
"github.com/oracle/coherence-go-client/coherence/processors"
"time"
)
// NamedMap defines the APIs to cache data, mapping keys to values, supporting full
// concurrency of retrievals and high expected concurrency for updates. Like traditional maps,
// this object cannot contain duplicate keys; each key can map to at most one value.
//
// As keys and values must be serializable in some manner. The current supported serialization method is JSON.
//
// Instances of this interface are typically acquired via a coherence.Session.
//
// Although all operations are thread-safe, retrieval operations do not entail locking, and there is no support for
// locking an entire map in a way to prevent all access. Retrievals reflect the results of the most recently completed
// update operations holding upon their onset.
//
// The type parameters are K = type of the key and V = type of the value.
type NamedMap[K comparable, V any] interface {
// AddLifecycleListener Adds a MapLifecycleListener that will receive events (truncated, released) that occur
// against the NamedMap.
AddLifecycleListener(listener MapLifecycleListener[K, V])
// AddFilterListener adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the NamedMap where entries satisfy the specified filters.Filter, with the key, and optionally,
// the old-value and new-value included.
AddFilterListener(ctx context.Context, listener MapListener[K, V], filter filters.Filter) error
// AddFilterListenerLite adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the NamedMap where entries satisfy the specified filters.Filter, with the key,
// the old-value and new-value included.
AddFilterListenerLite(ctx context.Context, listener MapListener[K, V], filter filters.Filter) error
// AddKeyListener adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the specified key within the NamedMap, with the key, old-value and new-value included.
AddKeyListener(ctx context.Context, listener MapListener[K, V], key K) error
// AddKeyListenerLite adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the specified key within the NamedMap, with the key, and optionally, the old-value and new-value included.
AddKeyListenerLite(ctx context.Context, listener MapListener[K, V], key K) error
// AddListener adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the NamedMap, with the key, old-value and new-value included.
// This call is equivalent to calling AddFilterListener with filters.Always as the filter.
AddListener(ctx context.Context, listener MapListener[K, V]) error
// AddListenerLite adds a MapListener that will receive events (inserts, updates, deletes) that occur
// against the NamedMap, with the key, and optionally, the old-value and new-value included.
// This call is equivalent to calling AddFilterListenerLite with filters.Always as the filter.
AddListenerLite(ctx context.Context, listener MapListener[K, V]) error
// Clear removes all mappings from the NamedMap.
Clear(ctx context.Context) error
// Truncate removes all mappings from the NamedMap.
// Note: the removal of entries caused by this truncate operation will not be observable.
Truncate(ctx context.Context) error
// Destroy releases and destroys this instance of NamedMap.
// Warning This method is used to completely destroy the specified
// NamedMap across the cluster. All references in the entire cluster to this
// cache will be invalidated, the data will be cleared, and all
// internal resources will be released.
// Note: the removal of entries caused by this truncate operation will not be observable.
Destroy(ctx context.Context) error
// Release releases the instance of NamedMap.
// This operation does not affect the contents of the NamedMap, but only releases the client
// resources. To access the NamedMap, you must get a new instance.
Release()
// ContainsKey returns true if the NamedMap contains a mapping for the specified key.
ContainsKey(ctx context.Context, key K) (bool, error)
// ContainsValue returns true if the NamedMap maps one or more keys to the specified value
ContainsValue(ctx context.Context, value V) (bool, error)
// ContainsEntry returns true if the NamedMap contains a mapping for the specified key and value.
ContainsEntry(ctx context.Context, key K, value V) (bool, error)
// IsEmpty returns true if the NamedMap contains no mappings.
IsEmpty(ctx context.Context) (bool, error)
// EntrySetFilter returns a channel from which entries satisfying the specified filter can be obtained.
// Each entry in the channel is of type *StreamEntry which basically wraps an error and the result.
// As always, the result must be accessed (and will be valid) only if the error is nil.
EntrySetFilter(ctx context.Context, filter filters.Filter) <-chan *StreamedEntry[K, V]
// EntrySet returns a channel from which all entries can be obtained.
// Note: the entries are paged internally to avoid excessive memory usage, but you need to be
// careful when running this operation against NamedMaps with large number of entries.
EntrySet(ctx context.Context) <-chan *StreamedEntry[K, V]
// Get returns the value to which the specified key is mapped. V will be nil if there was no previous value.
Get(ctx context.Context, key K) (*V, error)
// GetAll returns a channel from which entries satisfying the specified filter can be obtained.
// Each entry in the channel is of type *StreamEntry which basically wraps an error and the result.
// As always, the result must be accessed (and will be valid) only of the error is nil.
GetAll(ctx context.Context, keys []K) <-chan *StreamedEntry[K, V]
// GetOrDefault will return the value mapped to the specified key,
// or if there is no mapping, it will return the specified default.
GetOrDefault(ctx context.Context, key K, def V) (*V, error)
// InvokeAll invokes the specified processor against the entries matching the specified keys or filter. If no
// keys or filter are specified, then the function will be run against all entries.
// Functions are invoked atomically against a specific entry as the function may mutate the entry.
InvokeAll(ctx context.Context, keysOrFilter any, proc processors.Processor) <-chan *StreamedValue[V]
// KeySetFilter returns a channel from which keys of the entries that satisfy the filter can be obtained.
// Each entry in the channel is of type *StreamEntry which basically wraps an error and the key.
// As always, the result must be accessed (and will be valid) only of the error is nil.
KeySetFilter(ctx context.Context, filter filters.Filter) <-chan *StreamedKey[K]
// KeySet returns a channel from which keys of all entries can be obtained.
// Note: the entries are paged internally to avoid excessive memory usage, but you need to be
// careful when running this operation against NamedMaps with large number of entries.
KeySet(ctx context.Context) <-chan *StreamedKey[K]
// Name returns the name of the NamedMap.
Name() string
// Put associates the specified value with the specified key returning the previously
// mapped value. V will be nil if there was no previous value.
Put(ctx context.Context, key K, value V) (*V, error)
// PutAll copies all the mappings from the specified map to the NamedMap.
PutAll(ctx context.Context, entries map[K]V) error
// PutIfAbsent adds the specified mapping if the key is not already associated with a value in the NamedMap.
// Error will be equal to coherence. V will be nil if there was no previous value.
PutIfAbsent(ctx context.Context, key K, value V) (*V, error)
// Remove removes the mapping for a key from the NamedMap if it is present and returns the previously
// mapped value, if any. V will be nil if there was no previous value.
Remove(ctx context.Context, key K) (*V, error)
// RemoveLifecycleListener removes the lifecycle listener that was previously registered to receive events.
RemoveLifecycleListener(listener MapLifecycleListener[K, V])
// RemoveFilterListener removes the listener that was previously registered to receive events.
RemoveFilterListener(ctx context.Context, listener MapListener[K, V], filter filters.Filter) error
// RemoveKeyListener removes the listener that was previously registered to receive events.
RemoveKeyListener(ctx context.Context, listener MapListener[K, V], key K) error
// RemoveListener removes the listener that was previously registered to receive events.
RemoveListener(ctx context.Context, listener MapListener[K, V]) error
// RemoveMapping removes the entry for the specified key only if it is currently
// mapped to the specified value. Returns true if the value was removed.
RemoveMapping(ctx context.Context, key K, value V) (bool, error)
// Replace replaces the entry for the specified key only if it is
// currently mapped to some value.
Replace(ctx context.Context, key K, value V) (*V, error)
// ReplaceMapping replaces the entry for the specified key only if it is
// currently mapped to the value. Returns true if the value was replaced.
ReplaceMapping(ctx context.Context, key K, prevValue V, newValue V) (bool, error)
// Size returns the number of mappings contained within the NamedMap.
Size(ctx context.Context) (int, error)
// GetSession returns the Session associated with the NamedMap.
GetSession() *Session
// ValuesFilter returns a view of filtered values contained in the NamedMap.
// The returned channel will be asynchronously filled with values in the
// NamedMap that satisfy the filter.
ValuesFilter(ctx context.Context, filter filters.Filter) <-chan *StreamedValue[V]
// Values return a view of all values contained in the NamedMap.
// Note: the entries are paged internally to avoid excessive memory usage, but you need to be
// careful when running this operation against NamedMaps with large number of entries.
Values(ctx context.Context) <-chan *StreamedValue[V]
getBaseClient() *baseClient[K, V]
// IsReady returns whether this NamedMap is ready to be used.
// An example of when this method would return false would
// be where a partitioned cache service that owns this cache has no
// storage-enabled members.
// If it is not supported by the gRPC proxy, an error will be returned.
IsReady(ctx context.Context) (bool, error)
// GetNearCacheStats returns the [CacheStats] for a near cache for a [NamedMap] or [NamedCache].
// If no near cache is defined, nil is returned.
GetNearCacheStats() CacheStats
// GetCacheName returns the cache name of the [NamedMap] or [NamedCache].
GetCacheName() string
}
// NamedCache is syntactically identical in behaviour to a NamedMap, but additionally implements
// the PutWithExpiry operation. The type parameters are K = type of the key and V = type of the value.
type NamedCache[K comparable, V any] interface {
NamedMap[K, V]
// PutWithExpiry associates the specified value with the specified key. If the cache
// previously contained a value for this key, the old value is replaced.
// This variation of the Put(ctx context.Context, key K, value V)
// function allows the caller to specify an expiry (or "time to live")
// for the cache entry. If coherence.ExpiryNever < ttl < 1 millisecond,
// ttl is set to 1 millisecond.
// V will be nil if there was no previous value.
PutWithExpiry(ctx context.Context, key K, value V, ttl time.Duration) (*V, error)
}
// StreamedKey is wrapper object that wraps an error and a key. The Err object must be checked for errors
// before accessing the Key field.
type StreamedKey[K comparable] struct {
// Err contains the error (if any) while obtaining the key.
Err error
// Key contains the key of the entry.
Key K
}
// StreamedValue is wrapper object that wraps an error and a value. The Err object must be checked for errors
// before accessing the Value field.
type StreamedValue[V any] struct {
// Err contains the error (if any) while obtaining the value.
Err error
// Value contains the value of the entry.
Value V
}
// StreamedEntry is wrapper object that wraps an error and a Key and a Value .
// As always, the Err object must be checked for errors before accessing the Key or the Value fields.
type StreamedEntry[K comparable, V any] struct {
// Err contains the error (if any) while obtaining the value.
Err error
// Key contains the key of the entry.
Key K
// Value contains the value of the entry.
Value V
}
// Entry represents a returned entry from entryPageIterator.
type Entry[K comparable, V any] struct {
Key K
Value V
}