org.tiling.s3map
Class S3Map<V>

java.lang.Object
  java.util.AbstractMap<String,V>
      org.tiling.s3map.S3Map<V>

All Implemented Interfaces:

Map<String,V>

public class S3Map<V>
extends AbstractMap<String,V>
implements Map<String,V>

An implementation of Map which uses Amazon S3 as its backing store. All data is stored in a single S3 bucket, which is specified on construction of the map. The bucket is created if it doesn't already exist. (Note pre-existing buckets must only contain S3Map entries - other entries will corrupt the map.) This implementation provides all of the optional map operations, but does not permit null values and the null key (like Hashtable, and unlike HashMap). Furthermore, this implementation does not provide the two "standard" constructors that Map recommends since Amazon S3 connection details must always be supplied.

All keys are of type String, with the added restriction that their length (in UTF-8 encoding) must be between 1 and 1024 bytes (inclusive). If this latter condition is not met then a InvalidKeyException will be thrown.

All methods that interact with S3 (documented below) may throw the unchecked exception S3Exception if there is a problem communicating with S3. The exception contains diagnostic information.

Since Amazon S3 is a paid-for service it is important to have a feel for potentially how costly each map operation will be. The following table lists the cost of each public method call, in terms of the number of S3 operations, assuming there are n entries in the map. The cost is the worst-case cost, in some cases the cost may be lower - where this is the case it is noted. Notice that containsValue(Object), equals(Object), and hashCode() are surprisingly expensive since they are bound by their contract to operate on all their values.

Method	List Keys Operations (Keys retrieved)	Read Object Operations	Write Object Operations	Delete Object Operations	Notes
clear()	1 (n)	0	0	n
containsKey(Object)	0	1	0	0
containsValue(Object)	1 (n)	n	0	0	Likely fewer read operations if the map contains the object.
entrySet()	0	0	0	0	The iterator for the set returned by this method invokes one List Keys operation (retrieving a single key each time) and one Read Object operation for each element iterated over.
equals(Object)	1 (n) + n (1)	n	0	0	Fewer operations if maps are not equal.
get(Object)	0	1	0	0
keySet()	0	0	0	0	The iterator for the set returned by this method invokes one List Keys operation (retrieving a single key each time) for each element iterated over.
hashCode()	1 (n)	n	0	0
isEmpty()	1 (n)	0	0	0
put(String, Object)	0	1	1	0
putAll(Map)	0	k	k	0	Where k is the number of entries in map being added.
remove(Object)	0	1	0	1
size()	1 (n)	0	0	0
values()	0	0	0	0	The iterator for the set returned by this method invokes one List Keys operation (retrieving a single key each time) and one Read Object operation for each element iterated over.

Concurrency

This implementation is not synchronized. Like HashMap, if multiple threads access this map concurrently, and at least one of the threads modifies the map structurally, it must be synchronized externally. If multiple instances - possibly in separate Java Virtual Machines - access the same S3 bucket, then they need to take care to synchronize accesses that modify the map structurally. Note that this implementation, unlike HashMap, is not fail-fast.

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Constructor Summary

S3Map(String bucket, String awsAccessKeyId, String awsSecretAccessKey)

S3Map(String bucket, String awsAccessKeyId, String awsSecretAccessKey, Map<? extends String,? extends V> map)

S3Map(String bucket, String awsAccessKeyId, String awsSecretAccessKey, Serializer serializer)

Method Summary

void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
Set<Map.Entry<String,V>>	entrySet()
V	get(Object key)
Set<String>	keySet()
V	put(String key, V value)
V	remove(Object key)
int	size()
Collection<V>	values()

Methods inherited from class java.util.AbstractMap

clone, equals, hashCode, isEmpty, putAll, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode, isEmpty, putAll

Constructor Detail

S3Map

public S3Map(String bucket,
             String awsAccessKeyId,
             String awsSecretAccessKey)

S3Map

public S3Map(String bucket,
             String awsAccessKeyId,
             String awsSecretAccessKey,
             Map<? extends String,? extends V> map)

S3Map

public S3Map(String bucket,
             String awsAccessKeyId,
             String awsSecretAccessKey,
             Serializer serializer)

Method Detail

clear

public void clear()

Specified by:

clear in interface Map<String,V>

Overrides:

clear in class AbstractMap<String,V>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<String,V>

Overrides:

containsKey in class AbstractMap<String,V>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<String,V>

Overrides:

containsValue in class AbstractMap<String,V>

entrySet

public Set<Map.Entry<String,V>> entrySet()

Specified by:

entrySet in interface Map<String,V>

Specified by:

entrySet in class AbstractMap<String,V>

keySet

public Set<String> keySet()

Specified by:

keySet in interface Map<String,V>

Overrides:

keySet in class AbstractMap<String,V>

get

public V get(Object key)

Specified by:

get in interface Map<String,V>

Overrides:

get in class AbstractMap<String,V>

put

public V put(String key,
             V value)

Specified by:

put in interface Map<String,V>

Overrides:

put in class AbstractMap<String,V>

remove

public V remove(Object key)

Specified by:

remove in interface Map<String,V>

Overrides:

remove in class AbstractMap<String,V>

size

public int size()

Specified by:

size in interface Map<String,V>

Overrides:

size in class AbstractMap<String,V>

values

public Collection<V> values()

Specified by:

values in interface Map<String,V>

Overrides:

values in class AbstractMap<String,V>