Java Doc for FastMap.java in  » Science » javolution-5.2 » javolution » util » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Science » javolution 5.2 » javolution.util 
Source Cross Reference  Class Diagram Java Document (Java Doc) 


java.lang.Object
   javolution.util.FastMap

All known Subclasses:   j2me.util.HashMap,  j2me.util.LinkedHashMap,
FastMap
public class FastMap implements Map,Reusable,XMLSerializable,Realtime(Code)

This class represents a hash map with real-time behavior; smooth capacity increase and thread-safe without external synchronization when FastMap.isShared shared .

FastMap has a predictable iteration order, which is the order in which keys are inserted into the map (similar to java.util.LinkedHashMap collection class). If the map is marked FastMap.setShared(boolean) shared then all operations are thread-safe including iterations over the map's collections. Unlike ConcurrentHashMap, FastMap.get(Object) access never blocks; retrieval reflects the map state not older than the last time the accessing threads have been synchronized (for multi-processors systems synchronizing ensures that the CPU internal cache is not stale).

FastMap may use custom key comparators; the default comparator is either FastComparator.DIRECT DIRECT or FastComparator.REHASH REHASH based upon the current Javolution Configuration. Users may explicitly set the key comparator to FastComparator.DIRECT DIRECT for optimum performance when the hash codes are well distributed for all run-time platforms (e.g. calculated hash codes).

Custom key comparators are extremely useful for value retrieval when map's keys and argument keys are not of the same class (such as String and javolution.text.Text Text ( FastComparator.LEXICAL LEXICAL )), to substitute more efficient hash code calculations ( FastComparator.STRING STRING ) or for identity maps ( FastComparator.IDENTITY IDENTITY ):[code] FastMap identityMap = new FastMap().setKeyComparator(FastComparator.IDENTITY); [/code]

FastMap.Entry can quickly be iterated over (forward or backward) without using iterators. For example:[code] FastMap map = ...; for (FastMap.Entry e = map.head(), end = map.tail(); (e = e.getNext()) != end;) { String key = e.getKey(); // No typecast necessary. Thread value = e.getValue(); // No typecast necessary. }[/code]

Custom map implementations may override the FastMap.newEntry method in order to return their own Entry implementation (with additional fields for example).

FastMap are Reusable reusable ; they maintain an internal pool of Map.Entry objects. When an entry is removed from a map, it is automatically restored to its pool (unless the map is shared in which case the removed entry is candidate for garbage collection as it cannot be safely recycled).

Shared maps do not use internal synchronization, except in case of concurrent modifications of the map structure (entry added/deleted). Reads and iterations are never synchronized and never blocking. With regards to the memory model, shared maps are equivalent to shared non-volatile variables (no "happen before" guarantee). There are typically used as lookup tables. For example:[code] public class Unit { static FastMap labels = new FastMap().setShared(true); ... public String toString() { String label = labels.get(this); // No synchronization. return label != null ? label : makeLabel(); } }[/code]

Implementation Note: To maintain time-determinism, rehash/resize is performed only when the map's size is small (see chart). For large maps (size > 512), the collection is divided recursively into (64) smaller sub-maps. The cost of the dispatching (based upon hashcode value) has been measured to be at most 20% of the access time (and most often way less).


author:
   Jean-Marie Dautelle
version:
   5.2, September 11, 2007

Inner Class :public static class Entry implements Map.Entry,Record

Field Summary
static volatile  intONE_VOLATILE
    

Constructor Summary
public  FastMap()
     Creates a map whose capacity increment smoothly without large resize operations.
public  FastMap(String id)
     Creates a persistent map associated to the specified unique identifier (convenience method).
public  FastMap(int capacity)
     Creates a map of specified maximum size (a full resize may occur if the specififed capacity is exceeded).
public  FastMap(Map map)
     Creates a map containing the specified entries, in the order they are returned by the map iterator.

Method Summary
final public  voidclear()
     Removes all map's entries.
final public  booleancontainsKey(Object key)
     Indicates if this map contains a mapping for the specified key.
Parameters:
  key - the key whose presence in this map is to be tested.
final public  booleancontainsValue(Object value)
     Indicates if this map associates one or more keys to the specified value.
Parameters:
  value - the value whose presence in this map is to be tested.
final public  SetentrySet()
     Returns a FastCollection view of the mappings contained in this map.
public  booleanequals(Object obj)
     Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings (regardless of collection iteration order).
Parameters:
  obj - the object to be compared for equality with this map.
final public  Objectget(Object key)
     Returns the value to which this map associates the specified key. This method is always thread-safe regardless whether or not the map is marked FastMap.isShared() shared .
Parameters:
  key - the key whose associated value is to be returned.
final public  EntrygetEntry(Object key)
     Returns the entry with the specified key. This method is always thread-safe without synchronization.
Parameters:
  key - the key whose associated entry is to be returned.
public  FastComparatorgetKeyComparator()
     Returns the key comparator for this fast map.
public  FastComparatorgetValueComparator()
     Returns the value comparator for this fast map.
public  inthashCode()
     Returns the hash code value for this map.
final public  Entryhead()
     Returns the head entry of this map.
final public  booleanisEmpty()
     Indicates if this map contains no key-value mappings.
public  booleanisShared()
     Indicates if this map supports concurrent operations without synchronization (default unshared).
final public  SetkeySet()
     Returns a FastCollection view of the keys contained in this map.
protected  EntrynewEntry()
     Returns a new entry for this map; this method can be overriden by custom map implementations.
public static  FastMapnewInstance()
     Returns a potentially FastMap.recycle recycled map instance.
public  voidprintStatistics(PrintStream out)
     Prints the current statistics on this map. This method may help identify poorly defined hash functions. The average distance should be less than 20% (most of the entries are in their slots or close).
final public  Objectput(Object key, Object value)
     Associates the specified value with the specified key in this map. If this map previously contained a mapping for this key, the old value is replaced.
final public  voidputAll(Map map)
     Copies all of the mappings from the specified map to this map.
final public  ObjectputIfAbsent(Object key, Object value)
     Associates the specified value only if the specified key is not already associated.
public static  voidrecycle(FastMap instance)
     Recycles the specified map instance.
final public  Objectremove(Object key)
     Removes the entry for the specified key if present.
public  voidreset()
    
public  FastMapsetKeyComparator(FastComparator keyComparator)
     Sets the key comparator for this fast map.
Parameters:
  keyComparator - the key comparator.
public  FastMapsetShared(boolean isShared)
    

Sets the shared status of this map (whether the map is thread-safe or not).

public  FastMapsetValueComparator(FastComparator valueComparator)
     Sets the value comparator for this map.
Parameters:
  valueComparator - the value comparator.
final public  intsize()
     Returns the number of key-value mappings in this FastMap .
final public  Entrytail()
     Returns the tail entry of this map.
final public  StringtoString()
     Returns the String representation of this FastMap .
public  TexttoText()
     Returns the textual representation of this map.
final public  Mapunmodifiable()
     Returns the unmodifiable view associated to this map. Attempts to modify the returned map or to directly access its (modifiable) map entries (e.g.
final public  Collectionvalues()
     Returns a FastCollection view of the values contained in this map.

Field Detail
ONE_VOLATILE
static volatile int ONE_VOLATILE(Code)




Constructor Detail
FastMap
public FastMap()(Code)
Creates a map whose capacity increment smoothly without large resize operations.



FastMap
public FastMap(String id)(Code)
Creates a persistent map associated to the specified unique identifier (convenience method).
Parameters:
  id - the unique identifier for this map.
throws:
  IllegalArgumentException - if the identifier is not unique.
See Also:   javolution.context.PersistentContext.Reference



FastMap
public FastMap(int capacity)(Code)
Creates a map of specified maximum size (a full resize may occur if the specififed capacity is exceeded).
Parameters:
  capacity - the maximum capacity.



FastMap
public FastMap(Map map)(Code)
Creates a map containing the specified entries, in the order they are returned by the map iterator.
Parameters:
  map - the map whose entries are to be placed into this map.




Method Detail
clear
final public void clear()(Code)
Removes all map's entries. The entries are removed and recycled; unless this map is FastMap.isShared shared in which case the entries are candidate for garbage collection.

Note: Shared maps in ImmortalMemory (e.g. static) should not remove their entries as it could cause a memory leak (ImmortalMemory is never garbage collected), instead they should set their entry values to null.




containsKey
final public boolean containsKey(Object key)(Code)
Indicates if this map contains a mapping for the specified key.
Parameters:
  key - the key whose presence in this map is to be tested. true if this map contains a mapping for thespecified key; false otherwise.
throws:
  NullPointerException - if the key is null.



containsValue
final public boolean containsValue(Object value)(Code)
Indicates if this map associates one or more keys to the specified value.
Parameters:
  value - the value whose presence in this map is to be tested. true if this map maps one or more keys to thespecified value.
throws:
  NullPointerException - if the key is null.



entrySet
final public Set entrySet()(Code)
Returns a FastCollection view of the mappings contained in this map. Each element in the returned collection is a FastMap.Entry. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Collection.remove,removeAll, retainAll, and clear operations. It does not support the add or addAll operations. a collection view of the mappings contained in this map(instance of FastCollection).



equals
public boolean equals(Object obj)(Code)
Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings (regardless of collection iteration order).
Parameters:
  obj - the object to be compared for equality with this map. true if the specified object is equal to this map;false otherwise.



get
final public Object get(Object key)(Code)
Returns the value to which this map associates the specified key. This method is always thread-safe regardless whether or not the map is marked FastMap.isShared() shared .
Parameters:
  key - the key whose associated value is to be returned. the value to which this map maps the specified key, ornull if there is no mapping for the key.
throws:
  NullPointerException - if key is null.



getEntry
final public Entry getEntry(Object key)(Code)
Returns the entry with the specified key. This method is always thread-safe without synchronization.
Parameters:
  key - the key whose associated entry is to be returned. the entry for the specified key or null if none.



getKeyComparator
public FastComparator getKeyComparator()(Code)
Returns the key comparator for this fast map. the key comparator.



getValueComparator
public FastComparator getValueComparator()(Code)
Returns the value comparator for this fast map. the value comparator.



hashCode
public int hashCode()(Code)
Returns the hash code value for this map. the hash code value for this map.



head
final public Entry head()(Code)
Returns the head entry of this map. the entry such as head().getNext() holds the first map entry.



isEmpty
final public boolean isEmpty()(Code)
Indicates if this map contains no key-value mappings. true if this map contains no key-value mappings;false otherwise.



isShared
public boolean isShared()(Code)
Indicates if this map supports concurrent operations without synchronization (default unshared). true if this map is thread-safe; false otherwise.



keySet
final public Set keySet()(Code)
Returns a FastCollection view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. The set supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Collection.remove,removeAll, retainAll, and clear operations. It does not support the add or addAll operations. a set view of the keys contained in this map(instance of FastCollection).



newEntry
protected Entry newEntry()(Code)
Returns a new entry for this map; this method can be overriden by custom map implementations. a new entry.



newInstance
public static FastMap newInstance()(Code)
Returns a potentially FastMap.recycle recycled map instance. a new, preallocated or recycled map instance.



printStatistics
public void printStatistics(PrintStream out)(Code)
Prints the current statistics on this map. This method may help identify poorly defined hash functions. The average distance should be less than 20% (most of the entries are in their slots or close).
Parameters:
  out - the stream to use for output (e.g. System.out)



put
final public Object put(Object key, Object value)(Code)
Associates the specified value with the specified key in this map. If this map previously contained a mapping for this key, the old value is replaced. For FastMap.isShared() shared map, internal synchronization is performed only when new entries are created.
Parameters:
  key - the key with which the specified value is to be associated.
Parameters:
  value - the value to be associated with the specified key. the previous value associated with specified key, ornull if there was no mapping for key. Anull return can also indicate that the mappreviously associated null with the specified key.
throws:
  NullPointerException - if the key is null.



putAll
final public void putAll(Map map)(Code)
Copies all of the mappings from the specified map to this map.
Parameters:
  map - the mappings to be stored in this map.
throws:
  NullPointerException - the specified map is null,or the specified map contains null keys.



putIfAbsent
final public Object putIfAbsent(Object key, Object value)(Code)
Associates the specified value only if the specified key is not already associated. This is equivalent to:[code] if (!map.containsKey(key)) return map.put(key, value); else return map.get(key);[/code] except that for shared maps the action is performed atomically. For shared maps, this method guarantees that if two threads try to put the same key concurrently only one of them will succeed.
Parameters:
  key - the key with which the specified value is to be associated.
Parameters:
  value - the value to be associated with the specified key. the previous value associated with specified key, ornull if there was no mapping for key. Anull return can also indicate that the mappreviously associated null with the specified key.
throws:
  NullPointerException - if the key is null.



recycle
public static void recycle(FastMap instance)(Code)
Recycles the specified map instance.
Parameters:
  instance - the map instance to recycle.



remove
final public Object remove(Object key)(Code)
Removes the entry for the specified key if present. The entry is recycled if the map is not marked as FastMap.isShared shared ; otherwise the entry is candidate for garbage collection.

Note: Shared maps in ImmortalMemory (e.g. static) should not remove their entries as it could cause a memory leak (ImmortalMemory is never garbage collected), instead they should set their entry values to null.


Parameters:
  key - the key whose mapping is to be removed from the map. previous value associated with specified key, ornull if there was no mapping for key. Anull return can also indicate that the mappreviously associated null with the specified key.
throws:
  NullPointerException - if the key is null.



reset
public void reset()(Code)



setKeyComparator
public FastMap setKeyComparator(FastComparator keyComparator)(Code)
Sets the key comparator for this fast map.
Parameters:
  keyComparator - the key comparator. this



setShared
public FastMap setShared(boolean isShared)(Code)

Sets the shared status of this map (whether the map is thread-safe or not). Shared maps are typically used for lookup table (e.g. static instances in ImmortalMemory). They support concurrent access (e.g. iterations) without synchronization, the maps updates themselves are synchronized internally.

Unlike ConcurrentHashMap access to a shared map never blocks. Retrieval reflects the map state not older than the last time the accessing thread has been synchronized (for multi-processors systems synchronizing ensures that the CPU internal cache is not stale).


Parameters:
  isShared - true if this map is shared and thread-safe;false otherwise. this



setValueComparator
public FastMap setValueComparator(FastComparator valueComparator)(Code)
Sets the value comparator for this map.
Parameters:
  valueComparator - the value comparator. this



size
final public int size()(Code)
Returns the number of key-value mappings in this FastMap .

Note: If concurrent updates are performed, application should not rely upon the size during iterations.

this map's size.



tail
final public Entry tail()(Code)
Returns the tail entry of this map. the entry such as tail().getPrevious()holds the last map entry.



toString
final public String toString()(Code)
Returns the String representation of this FastMap . toText().toString()



toText
public Text toText()(Code)
Returns the textual representation of this map. the textual representation of the entry set.



unmodifiable
final public Map unmodifiable()(Code)
Returns the unmodifiable view associated to this map. Attempts to modify the returned map or to directly access its (modifiable) map entries (e.g. unmodifiable().entrySet()) result in an UnsupportedOperationException being thrown. Unmodifiable FastCollection views of this map keys and values are nonetheless obtainable (e.g. unmodifiable().keySet(), unmodifiable().values()). an unmodifiable view of this map.



values
final public Collection values()(Code)
Returns a FastCollection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. The collection supports element removal, which removes the corresponding mapping from this map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations. a collection view of the values contained in this map (instance of FastCollection).



Methods inherited from java.lang.Object
native protected Object clone() throws CloneNotSupportedException(Code)(Java Doc)
public boolean equals(Object obj)(Code)(Java Doc)
protected void finalize() throws Throwable(Code)(Java Doc)
final native public Class getClass()(Code)(Java Doc)
native public int hashCode()(Code)(Java Doc)
final native public void notify()(Code)(Java Doc)
final native public void notifyAll()(Code)(Java Doc)
public String toString()(Code)(Java Doc)
final native public void wait(long timeout) throws InterruptedException(Code)(Java Doc)
final public void wait(long timeout, int nanos) throws InterruptedException(Code)(Java Doc)
final public void wait() throws InterruptedException(Code)(Java Doc)

www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.