bloritsch 2002/05/31 14:15:42
Modified: collections/src/java/org/apache/avalon/excalibur/collections
BucketMap.java
Log:
make the comments worthwile
Revision Changes Path
1.16 +58 -37
jakarta-avalon-excalibur/collections/src/java/org/apache/avalon/excalibur/collections/BucketMap.java
Index: BucketMap.java
===================================================================
RCS file:
/home/cvs/jakarta-avalon-excalibur/collections/src/java/org/apache/avalon/excalibur/collections/BucketMap.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- BucketMap.java 8 Apr 2002 10:11:17 -0000 1.15
+++ BucketMap.java 31 May 2002 21:15:42 -0000 1.16
@@ -14,12 +14,15 @@
import java.util.Set;
/**
- * A BucketMap is an efficient ThreadSafe implementation of a Map. The
- * map only supports get(), put(), and contains().
+ * A BucketMap is an efficient thread-safe implementation of the
+ * <code>java.util.Map</code>. The map supports <code>get</code>,
+ * <code>put</code>, and <code>contains</code> methods most efficiently.
+ * The other methods are supported, but are ver inneficient compared to
+ * other <code>java.util.Map</code> implementations.
*
* @author <a href="[EMAIL PROTECTED]">Berin Loritsch</a>
* @author <a href="[EMAIL PROTECTED]">Gerhard Froehlich</a>
- * @version CVS $Revision: 1.15 $ $Date: 2002/04/08 10:11:17 $
+ * @version CVS $Revision: 1.16 $ $Date: 2002/05/31 21:15:42 $
* @since 4.0
*/
public final class BucketMap implements Map
@@ -29,12 +32,21 @@
private final Object[] m_locks;
/**
+ * Initializes the map with the default number of buckets (255).
*/
public BucketMap()
{
this( DEFAULT_BUCKETS );
}
+ /**
+ * Initializes the map with a specified number of buckets. The number
+ * of buckets is never below 17, and is always an odd number (BucketMap
+ * ensures this). The number of buckets is inversely proportional to the
+ * chances for thread contention. The fewer buckets, the more chances
for
+ * thread contention. The more buckets the fewer chances for thread
+ * contention.
+ */
public BucketMap( int numBuckets )
{
int size = Math.max( 17, numBuckets );
@@ -54,17 +66,29 @@
}
}
- private final int getHash( Object key )
+ /**
+ * Determine the exact hash entry for the key. The hash algorithm
+ * is rather simplistic, but it does the job:
+ *
+ * <pre>
+ * He = |Hk mod n|
+ * </pre>
+ *
+ * <p>
+ * He is the entry's hashCode, Hk is the key's hashCode, and n is
+ * the number of buckets.
+ * </p>
+ */
+ private static final int getHash( Object key )
{
final int hash = key.hashCode() % m_buckets.length;
return ( hash < 0 ) ? hash * -1 : hash;
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Obtain a Set for the keys. This operation crosses bucket boundaries,
+ * so it is less efficient, and greatly increases the chance for thread
+ * contention.
*/
public Set keySet()
{
@@ -89,9 +113,6 @@
/**
* Returns the current number of key, value pairs.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
*/
public int size()
{
@@ -116,9 +137,6 @@
/**
* Put a reference in the Map.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
*/
public Object put( final Object key, final Object value )
{
@@ -169,10 +187,7 @@
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Get an object from the Map by the key
*/
public Object get( final Object key )
{
@@ -202,10 +217,7 @@
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Checks to see if the provided key exists in the Map.
*/
public boolean containsKey( final Object key )
{
@@ -235,10 +247,9 @@
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Checks to see if a value exists. This operation crosses bucket
+ * boundaries, so it is less efficient, and greatly increases the chance
+ * for thread contention.
*/
public boolean containsValue( final Object value )
{
@@ -269,10 +280,9 @@
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Obtain a Set for the values. This operation crosses bucket
boundaries,
+ * so it is less efficient, and greatly increases the chance for thread
+ * contention.
*/
public Collection values()
{
@@ -296,10 +306,9 @@
}
/**
- * Add an object into the buffer.
- *
- * @throws BufferOverflowException if adding this element exceeds the
- * buffer's capacity.
+ * Obtain a Set for the entries. This operation crosses bucket
boundaries,
+ * so it is less efficient, and greatly increases the chance for thread
+ * contention.
*/
public Set entrySet()
{
@@ -337,9 +346,7 @@
}
/**
- * Removes the next object from the buffer.
- *
- * @throws BufferUnderflowException if the buffer is already empty
+ * Removes the object from the Map based on the key.
*/
public Object remove( Object key )
{
@@ -382,6 +389,9 @@
return null;
}
+ /**
+ * Tests if the Map is empty.
+ */
public final boolean isEmpty()
{
for( int i = 0; i < m_buckets.length; i++ )
@@ -395,6 +405,9 @@
return true;
}
+ /**
+ * Removes all the entries from the Map.
+ */
public final void clear()
{
for( int i = 0; i < m_buckets.length; i++ )
@@ -403,6 +416,9 @@
}
}
+ /**
+ * The Map.Entry for the BucketMap.
+ */
private static final class Node implements Map.Entry
{
protected Object key;
@@ -417,6 +433,11 @@
public Object getValue()
{
return value;
+ }
+
+ public long hashCode()
+ {
+ return getHash( key );
}
public Object setValue( Object val )
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
