insertBucket and updateBucket in BucketBasedCacheStore should be combined into 1 method (storeBucket?). Javadocs should be updated accordingly, to reflect that the bucket is persisted, and if it doesn't already exist, it will be created anew.

2 impls of this (FileCacheStore and CloudCacheStore) already delegate updateBucket() --> insertBucket(). The only impl that treats these 2 calls differently is the JdbcBinaryCacheStore. But this is incorrect since JdbcBinaryCacheStore.insertBucket() throws an exception if the row already exists. And this can happen if, for example, the cache store is in async mode. Or if it is shared.

So the JdbcBinaryCacheStore would first have to be fixed, to use SQL such as "INSERT... OR UPDATE", e.g.:
http://dev.mysql.com/doc/refman/5.0/en/insert-on-duplicate.html