public class MemcachedStorageService extends net.shibboleth.utilities.java.support.component.AbstractIdentifiableInitializableComponent implements StorageService
https://code.google.com/p/memcached/wiki/NewProgrammingTricks#Namespacing
This storage service supports arbitrary-length context names and keys despite the 250-byte limit on memcached keys. Keys whose length is greater than 250 bytes are hashed using the SHA-512 algorithm and hex encoded to produce a 128-character key that is stored in memcached. Collisions are avoided irrespective of hashing by using the memcached add operation on all create operations which guarantees that an entry is created if and only if a key of the same value does not already exist. Note that context names and keys are assumed to have single-byte encodings in UTF-8 (i.e. ASCII characters) such that key lengths are equal to their size in bytes. Hashed keys naturally meet this requirement.
An optional context key-tracking feature is available to support updateContextExpiration(String, Long)
.
Key tracking is disabled by default, but can be enabled by setting the enableContextKeyTracking
parameter in the MemcachedStorageService(net.spy.memcached.MemcachedClient, int, boolean)
constructor.
While there is modest performance impact for create and delete operations, the feature limits the number of keys
per context. With the default 1M memcached slab size, in the worst case 4180 keys are permitted per context.
In many if not most situations the value is easily double that. The limitation can be overcome by increasing the
slab size, which decreases overall cache memory consumption efficiency. When key tracking is disabled, there is no
limit on the number of keys per context other than overall cache capacity.
Limitations and requirements
deleteWithVersion(long, String, String)
and deleteWithVersion(long, Object)
will throw runtime errors under the ASCII protocol.Modifier and Type | Field and Description |
---|---|
protected static String |
CTX_KEY_BLACKLIST_SUFFIX
Key suffix for entry that contains a list of blacklisted (deleted) context keys.
|
protected static String |
CTX_KEY_LIST_SUFFIX
Key suffix for entry that contains a list of context keys.
|
Constructor and Description |
---|
MemcachedStorageService(net.spy.memcached.MemcachedClient client,
int timeout)
Creates a new instance.
|
MemcachedStorageService(net.spy.memcached.MemcachedClient client,
int timeout,
boolean enableContextKeyTracking)
Creates a new instance with optional context key tracking.
|
Modifier and Type | Method and Description |
---|---|
boolean |
create(Object value)
Creates a new record in the store using an annotated object as the source.
|
boolean |
create(String context,
String key,
Object value,
StorageSerializer serializer,
Long expiration)
Creates a new record in the store with an expiration, using a custom serialization
process for an arbitrary object.
|
boolean |
create(String context,
String key,
String value,
Long expiration)
Creates a new record in the store with an expiration.
|
protected String |
createNamespace(String context)
Creates a cache-wide unique namespace for the given context name.
|
boolean |
delete(Object value)
Deletes an existing record from the store, using an annotated object as the source.
|
boolean |
delete(String context,
String key)
Deletes an existing record from the store.
|
void |
deleteContext(String context)
Forcibly removes all records in a given context along with any
associated resources devoted to maintaining the context.
|
boolean |
deleteWithVersion(long version,
Object value)
Deletes an existing record from the store, using an annotated object as the source, if it
currently has a specified version.
|
boolean |
deleteWithVersion(long version,
String context,
String key)
Deletes an existing record from the store if it currently has a specified version.
|
protected void |
doDestroy() |
StorageCapabilities |
getCapabilities()
Returns the capabilities of the underlying store.
|
protected String |
lookupNamespace(String context)
Looks up the namespace for the given context name in the cache.
|
Object |
read(Object value)
Returns an existing record from the store, if one exists, and uses it to
update the annotated fields of a target object.
|
StorageRecord |
read(String context,
String key)
Returns an existing record from the store, if one exists.
|
net.shibboleth.utilities.java.support.collection.Pair<Long,StorageRecord> |
read(String context,
String key,
long version)
Returns an existing record from the store, along with its version.
|
void |
reap(String context)
Manually trigger a cleanup of expired records.
|
void |
setCapabilities(MemcachedStorageCapabilities capabilities)
Sets the storage capabilities.
|
boolean |
update(Object value)
Updates an existing record in the store, using an annotated object as the source.
|
boolean |
update(String context,
String key,
Object value,
StorageSerializer serializer,
Long expiration)
Updates an existing record in the store using a custom serialization strategy.
|
boolean |
update(String context,
String key,
String value,
Long expiration)
Updates an existing record in the store.
|
void |
updateContextExpiration(String context,
Long expiration)
Updates the expiration time of all records in the context.
|
boolean |
updateExpiration(Object value)
Updates expiration of an existing record in the store, using an annotated object as the source.
|
boolean |
updateExpiration(String context,
String key,
Long expiration)
Updates expiration of an existing record in the store.
|
Long |
updateWithVersion(long version,
Object value)
Updates an existing record in the store, if a version matches, using an annotated object as the source.
|
Long |
updateWithVersion(long version,
String context,
String key,
Object value,
StorageSerializer serializer,
Long expiration)
Updates an existing record in the store, if a version matches, using a custom serialization strategy.
|
Long |
updateWithVersion(long version,
String context,
String key,
String value,
Long expiration)
Updates an existing record in the store, if a version matches.
|
setId
doInitialize, getId
destroy, initialize, isDestroyed, isInitialized
protected static final String CTX_KEY_LIST_SUFFIX
protected static final String CTX_KEY_BLACKLIST_SUFFIX
public MemcachedStorageService(@Nonnull net.spy.memcached.MemcachedClient client, @Positive int timeout)
client
- Memcached client object. The client MUST be configured to use the binary memcached protocol,
i.e. BinaryConnectionFactory
, in order for
deleteWithVersion(long, String, String)
and deleteWithVersion(long, Object)
to work correctly. The binary protocol is recommended for efficiency as well.timeout
- Memcached operation timeout in seconds.public MemcachedStorageService(@Nonnull net.spy.memcached.MemcachedClient client, @Positive int timeout, boolean enableContextKeyTracking)
client
- Memcached client object. The client MUST be configured to use the binary memcached protocol,
i.e. BinaryConnectionFactory
, in order for
deleteWithVersion(long, String, String)
and deleteWithVersion(long, Object)
to work correctly. The binary protocol is recommended for efficiency as well.timeout
- Memcached operation timeout in seconds.enableContextKeyTracking
- True to enable context key tracking, false otherwise. NOTE
this flag must be set to true
in order for
updateContextExpiration(String, Long)
to work. If that capability is
not needed, the flag should be set to false
for better
performance. The feature is disabled by default.@Nonnull public StorageCapabilities getCapabilities()
StorageService
getCapabilities
in interface StorageService
public void setCapabilities(@Nonnull MemcachedStorageCapabilities capabilities)
edu.vt.middleware.idp.storage.MemcachedStorageCapabilities#valueSize
should be set equal to the
chosen slab size.capabilities
- Memcached storage capabilities.public boolean create(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable @Positive Long expiration) throws IOException
StorageService
create
in interface StorageService
context
- a storage context labelkey
- a key unique to contextvalue
- value to storeexpiration
- expiration for record, or nullIOException
- if fatal errors occur in the insertion processpublic boolean create(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull Object value, @Nonnull StorageSerializer serializer, @Nullable @Positive Long expiration) throws IOException
StorageService
create
in interface StorageService
context
- a storage context labelkey
- a key unique to contextvalue
- object to storeserializer
- custom serializer for the objectexpiration
- expiration for record, or nullIOException
- if fatal errors occur in the insertion processpublic boolean create(@Nonnull Object value) throws IOException
StorageService
The individual parameters for the creation are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
create
in interface StorageService
value
- object to storeIOException
- if fatal errors occur in the insertion processpublic StorageRecord read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException
StorageService
read
in interface StorageService
context
- a storage context labelkey
- a key unique to contextIOException
- if errors occur in the read processpublic Object read(@Nonnull Object value) throws IOException
StorageService
The context and key to look up are obtained from the target object, and the value and expiration are written back, using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
read
in interface StorageService
value
- object to look up and populateIOException
- if errors occur in the read processpublic net.shibboleth.utilities.java.support.collection.Pair<Long,StorageRecord> read(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Positive long version) throws IOException
StorageService
The first member of the pair returned will contain the version of the record in the store, or will be null if no record exists. The second member will contain the record read back. If null, the record either didn't exist (if the first member was also null) or the record was the same version as that supplied by the caller.
read
in interface StorageService
context
- a storage context labelkey
- a key unique to contextversion
- only return record if newer than supplied versionIOException
- if errors occur in the read processpublic boolean update(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable @Positive Long expiration) throws IOException
StorageService
update
in interface StorageService
context
- a storage context labelkey
- a key unique to contextvalue
- updated valueexpiration
- expiration for record, or nullIOException
- if errors occur in the update processpublic boolean update(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull Object value, @Nonnull StorageSerializer serializer, @Nullable @Positive Long expiration) throws IOException
StorageService
update
in interface StorageService
context
- a storage context labelkey
- a key unique to contextvalue
- updated valueserializer
- custom serializerexpiration
- expiration for record, or nullIOException
- if errors occur in the update processpublic boolean update(@Nonnull Object value) throws IOException
StorageService
The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
update
in interface StorageService
value
- object to update fromIOException
- if errors occur in the update processpublic Long updateWithVersion(@Positive long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull @NotEmpty String value, @Nullable @Positive Long expiration) throws IOException, VersionMismatchException
StorageService
updateWithVersion
in interface StorageService
version
- only update if the current version matches this valuecontext
- a storage context labelkey
- a key unique to contextvalue
- updated valueexpiration
- expiration for record, or nullIOException
- if errors occur in the update processVersionMismatchException
- if the record has already been updated to a newer versionpublic Long updateWithVersion(@Positive long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nonnull Object value, @Nonnull StorageSerializer serializer, @Nullable @Positive Long expiration) throws IOException, VersionMismatchException
StorageService
updateWithVersion
in interface StorageService
version
- only update if the current version matches this valuecontext
- a storage context labelkey
- a key unique to contextvalue
- updated valueserializer
- custom serializerexpiration
- expiration for record, or nullIOException
- if errors occur in the update processVersionMismatchException
- if the record has already been updated to a newer versionpublic Long updateWithVersion(@Positive long version, @Nonnull Object value) throws IOException, VersionMismatchException
StorageService
The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
updateWithVersion
in interface StorageService
version
- only update if the current version matches this valuevalue
- object to update fromIOException
- if errors occur in the update processVersionMismatchException
- if the record has already been updated to a newer versionpublic boolean updateExpiration(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key, @Nullable @Positive Long expiration) throws IOException
StorageService
updateExpiration
in interface StorageService
context
- a storage context labelkey
- a key unique to contextexpiration
- expiration for record, or nullIOException
- if errors occur in the update processpublic boolean updateExpiration(@Nonnull Object value) throws IOException
StorageService
The individual parameters for the update are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
updateExpiration
in interface StorageService
value
- object to update fromIOException
- if errors occur in the update processpublic boolean delete(@Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException
StorageService
delete
in interface StorageService
context
- a storage context labelkey
- a key unique to contextIOException
- if errors occur in the deletion processpublic boolean delete(@Nonnull Object value) throws IOException
StorageService
The individual parameters for the deletion are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
delete
in interface StorageService
value
- object to deleteIOException
- if errors occur in the deletion processpublic boolean deleteWithVersion(@Positive long version, @Nonnull @NotEmpty String context, @Nonnull @NotEmpty String key) throws IOException, VersionMismatchException
StorageService
deleteWithVersion
in interface StorageService
version
- record version to deletecontext
- a storage context labelkey
- a key unique to contextIOException
- if errors occur in the deletion processVersionMismatchException
- if the record has already been updated to a newer versionpublic boolean deleteWithVersion(@Positive long version, @Nonnull Object value) throws IOException, VersionMismatchException
StorageService
The individual parameters for the deletion are extracted from the object using the annotations in the org.opensaml.storage.annotation package. If any are missing, or a field inaccessible, a runtime exception of some kind will occur.
deleteWithVersion
in interface StorageService
version
- record version to deletevalue
- object to deleteIOException
- if errors occur in the deletion processVersionMismatchException
- if the record has already been updated to a newer versionpublic void reap(@Nonnull @NotEmpty String context) throws IOException
StorageService
reap
in interface StorageService
context
- a storage context labelIOException
- if errors occur in the cleanup processpublic void updateContextExpiration(@Nonnull @NotEmpty String context, @Nullable Long expiration) throws IOException
StorageService
updateContextExpiration
in interface StorageService
context
- a storage context labelexpiration
- a new expiration timestamp, or nullIOException
- if errors occur in the cleanup processpublic void deleteContext(@Nonnull @NotEmpty String context) throws IOException
StorageService
deleteContext
in interface StorageService
context
- a storage context labelIOException
- if errors occur in the cleanup processprotected void doDestroy()
doDestroy
in class net.shibboleth.utilities.java.support.component.AbstractInitializableComponent
protected String lookupNamespace(String context) throws IOException
context
- Context name.IOException
- On memcached operation errors.protected String createNamespace(String context) throws IOException
context
- Context name.IOException
- On memcached operation errors.Copyright © 2016. All rights reserved.