com.webobjects.foundation
Class NSDictionary

java.lang.Object
  com.webobjects.foundation.NSDictionary

All Implemented Interfaces:

NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Serializable, Cloneable, Map

Direct Known Subclasses:

NSMutableDictionary

public class NSDictionary
extends Object
implements Cloneable, Serializable, NSCoding, NSKeyValueCoding, NSKeyValueCodingAdditions, Map

The NSDictionary class declares an API for objects that manage immutable associations of keys and values. This class, or its subclass NSMutableDictionary, is used when a convenient and efficient way is needed to retrieve data associated with an arbitrary key. (For convenience, we use the term dictionary to refer to any instance of one of these classes without specifying its exact class membership.)

A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key, and a second object which is that key's value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by equals ).

An instance of NSDictionary is an immutable dictionary: you establish its entries when it is created, and cannot modify them afterwards. An instance of NSMutableDictionary is a mutable dictionary: you can add or delete entries at any time, and the object automatically allocates memory as needed.

Methods that add entries to dictionaries, whether during construction (for all dictionaries) or modification (for mutable dictionaries), add each value object to the dictionary directly. This means that you must ensure that the keys do not change. If you expect your keys to change for any reason, you should make copies of the keys and add the copies to the dictionary or otherwise guarantee that the keys will not change with respect to either the equals or hashCode methods. java.lang.String objects are immutable and make good keys.

The NSDictionary methods that provide the basis for all NSDictionary's other the NSDictionary methods that provide the basis for all NSDictionary's other methods; that is, all other methods are implemented in terms of these four. If you create a subclass of NSDictionary, you need only ensure that these base methods work properly. Having done so, you can be sure that all your subclass's inherited methods operate properly.

NSDictionary's Base API

Method	Description
count	Returns the number of entries in the dictionary.
objectForKey	Returns the value associated with a given key.
keysNoCopy	Returns a natural language array containing the keys in the dictionary.
objectsNoCopy	Returns a natural language array containing the objects in the dictionary.

The other methods declared here operate by invoking one or more of these primitives. The non-primitive methods provide convenient ways of accessing multiple entries at once.

See Also:

Map, HashMap, Hashtable, NSDictionary._count, NSDictionary.objectForKey(java.lang.Object), Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSCoding

NSCoding.Support

Nested classes/interfaces inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

NSKeyValueCodingAdditions.DefaultImplementation, NSKeyValueCodingAdditions.Utility

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

Map.Entry

Field Summary

static boolean	CheckForNull Convenience for the constructor methods
static NSDictionary	EmptyDictionary A NSDictionary instance containing no entries which may be shared.
static boolean	IgnoreNull Convenience for the constructor methods

Fields inherited from interface com.webobjects.foundation.NSKeyValueCodingAdditions

KeyPathSeparator

Constructor Summary

NSDictionary()
Creates an empty dictionary.

NSDictionary(Dictionary dictionary, boolean ignoreNull)
Creates a dictionary containing the keys and values found in dictionary.

NSDictionary(Map map)
Creates a dictionary containing the keys and values found in Map.

NSDictionary(Map map, boolean ignoreNull)
Creates a dictionary containing the keys and values found in Map.

NSDictionary(NSArray objects, NSArray keys)
Creates an NSDictionary with entries from the contents of the keys and objects NSArrays.

NSDictionary(NSDictionary otherDictionary)
Creates a dictionary containing the keys and values found in otherDictionary.

NSDictionary(Object[] objects, Object[] keys)
Creates an NSDictionary with entries from the contents of the keys and objects arrays.

NSDictionary(Object object, Object key)
Creates a dictionary containing a single object object for a single key key.

Method Summary

NSArray	allKeys() The order of the elements in the returned array is not defined.
NSArray	allKeysForObject(Object object) Finds all occurrences of the value object in the dictionary and returns a new array with the corresponding keys.
NSArray	allValues() The order of the values in the array is not defined.
Class	classForCoder() Conformance to NSCoding.
void	clear() Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
Object	clone() Returns a copy (an NSDictionary object) of this dictionary.
boolean	containsKey(Object key) NSDictionaries do not allow null keys which differs from the java.util.Map specification.
boolean	containsValue(Object value) NSDictionaries do not allow for null values which differs from the java.util.Map specification.
int	count() This method returns a count of the number of key-value pairs.
static Object	decodeObject(NSCoder coder) Creates an NSDictionary from the data in coder.
static NSDictionary	emptyDictionary() Returns the empty NSDictionary (immutable).
void	encodeWithCoder(NSCoder coder) Encodes the receiver using coder.
Set	entrySet()
boolean	equals(Object object) Compares this dictionary to object.
Object	get(Object key) Conforms to NSDictionary.objectForKey() specification.
int	hashCode()
HashMap	hashMap()
Hashtable	hashtable()
NSDictionary	immutableClone() Since NSDictionaries are immutable, there's no need to make an actual copy.
boolean	isEmpty()
boolean	isEqualToDictionary(NSDictionary otherDictionary) Provided for backward compatibility.
Enumeration	keyEnumerator() This method provides a java.util.Enumeration which can be used to access each key in this dictionary.
Set	keySet()
protected Object[]	keysNoCopy() This method should only be used by subclasses.
NSMutableDictionary	mutableClone()
Enumeration	objectEnumerator() This method provides a java.util.Enumeration which can be used to access each value in this dictionary.
Object	objectForKey(Object key) This method returns the Object associated with key
NSArray	objectsForKeys(NSArray keys, Object notFoundMarker) This method takes a subset of the dictionary as specified by the array of keys and returns an array of the value objects associated with each of the keys.
protected Object[]	objectsNoCopy() This method should only be used by subclasses.
Object	put(Object key, Object value) Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
void	putAll(Map t) Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
Object	remove(Object key) Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.
int	size()
void	takeValueForKey(Object value, String key) Conformance to NSKeyValueCoding.
void	takeValueForKeyPath(Object value, String keyPath) Conformance to NSKeyValueCodingAdditions.
String	toString()
Object	valueForKey(String key) Conformance to NSKeyValueCoding.
Object	valueForKeyPath(String keyPath) Conformance to NSKeyValueCodingAdditions.
Collection	values() Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Methods inherited from class java.lang.Object

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

Field Detail

EmptyDictionary

public static final NSDictionary EmptyDictionary

A NSDictionary instance containing no entries which may be shared.

CheckForNull

public static final boolean CheckForNull

Convenience for the constructor methods

See Also:

Constant Field Values

IgnoreNull

public static final boolean IgnoreNull

Convenience for the constructor methods

See Also:

Constant Field Values

Constructor Detail

NSDictionary

public NSDictionary()

Creates an empty dictionary. To improve performance, the EmptyDictionary constant should be used instead.

See Also:

NSDictionary.EmptyDictionary

NSDictionary

public NSDictionary(Object object,
                    Object key)

Creates a dictionary containing a single object object for a single key key. null is an illegal value for both object and key.

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

Parameters:

object - object to be stored in the dictionary

key - key corresponding to the object to be stored in the dictionary

NSDictionary

public NSDictionary(Object[] objects,
                    Object[] keys)

Creates an NSDictionary with entries from the contents of the keys and objects arrays. This method steps through objects and keys, creating entries in the new dictionary as it goes. Each key object and its corresponding value object is added directly to the dictionary. None of the objects are permitted to be null.

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

Parameters:

objects - array of objects to be stored in the dictionary

keys - array of keys corresponding to the object to be stored in the dictionary

Throws:

java.lang.IllegalArgumentException - if the object array and the key array do not have the same size, or any element is null

NSDictionary

public NSDictionary(NSArray objects,
                    NSArray keys)

Creates an NSDictionary with entries from the contents of the keys and objects NSArrays. This method steps through objects and keys, creating entries in the new dictionary as it goes. Each key object and its corresponding value object is added directly to the dictionary.

Note: NSDictionary assumes that key objects are immutable. If your key objects are mutable, you should make copies of them and add the copies to the dictionary.

Parameters:

objects - array of objects to be stored in the dictionary

keys - array of keys corresponding to the objects to be stored in the dictionary

Throws:

java.lang.IllegalArgumentException - if the object array and the key array do not have the same size

NSDictionary

public NSDictionary(NSDictionary otherDictionary)

Creates a dictionary containing the keys and values found in otherDictionary.

Parameters:

otherDictionary - the input dictionary from which the duplicate dictionary is to be created

NSDictionary

public NSDictionary(Map map,
                    boolean ignoreNull)

Creates a dictionary containing the keys and values found in Map. If ignoreNull is false, throws an IllegalArgumentException if any key or value in dictionary is null. Throws a NullPointerException if map is null.

Parameters:

map - the input Map from which the current dictionary is to be created

ignoreNull - true if null is to be allowed in the input fields.

Throws:

java.lang.IllegalArgumentException - when null is not allowed and a null is encountered

Since:

5.3

See Also:

Map

NSDictionary

public NSDictionary(Map map)

Creates a dictionary containing the keys and values found in Map. Throws an IllegalArgumentException if any key or value in dictionary is null. Throws a NullPointerException if map is null.

Parameters:

map - the input Map from which the current dictionary is to be created

Throws:

java.lang.IllegalArgumentException - when null is not allowed and a null is encountered

Since:

5.4

See Also:

Map

NSDictionary

public NSDictionary(Dictionary dictionary,
                    boolean ignoreNull)

Creates a dictionary containing the keys and values found in dictionary. If ignoreNull is false, throws an IllegalArgumentException if any key or value in dictionary is null.

Parameters:

dictionary - the input dictionary from which the current dictionary is to be created

ignoreNull - true if null is to be allowed in the input fields.

Throws:

java.lang.IllegalArgumentException - when null is not allowed and a null is encountered

Method Detail

keysNoCopy

protected Object[] keysNoCopy()

This method should only be used by subclasses. The order of the values in the returned array is not defined. This method is similar to allKeys except the keys might not be copied.

Returns:

an array containing the dictionary's values, or an empty array if the dictionary has no entries

See Also:

NSDictionary.objectsNoCopy(), NSDictionary.allKeys()

objectsNoCopy

protected Object[] objectsNoCopy()

This method should only be used by subclasses. The order of the values in the array isn't defined. This method is similar to allValues except the objects might not be copied.

Returns:

an array containing the dictionary's values, or an empty array if the dictionary has no entries

See Also:

NSDictionary.keysNoCopy(), NSDictionary.allValues()

count

public int count()

This method returns a count of the number of key-value pairs.

Returns:

the number of entries in the dictionary.

objectForKey

public Object objectForKey(Object key)

This method returns the Object associated with key

Parameters:

key - the key to be searched for

Returns:

the value for key, or null if no value is associated with key

See Also:

NSDictionary.allKeys(), NSDictionary.allValues()

hashtable

public Hashtable hashtable()

Returns:

a copy of this dictionary transformed into a java.util.Hashtable

hashMap

public HashMap hashMap()

Returns:

a copy of this dictionary transformed into a java.util.HashMap

Since:

5.3

allKeysForObject

public NSArray allKeysForObject(Object object)

Finds all occurrences of the value object in the dictionary and returns a new array with the corresponding keys. Each object in the dictionary is sent an equals message to determine if it is equalivalent to object. If no Object matching object is found, this method returns an empty array.

Parameters:

object - the search target in the dictionary

Returns:

an array with all the occurrences of keys associated with object

See Also:

NSDictionary.allKeys(), NSDictionary.keyEnumerator()

objectsForKeys

public NSArray objectsForKeys(NSArray keys,
                              Object notFoundMarker)

This method takes a subset of the dictionary as specified by the array of keys and returns an array of the value objects associated with each of the keys. The objects in the returned array and the keys array have a one-for-one correspondence, so that the nth object in the returned array corresponds to the nth key in keys. If an object is not found in this dictionary for a corresponding key, the notFoundMarker Object is placed in that key's position in the resultant array.

Parameters:

keys - a subset of keys

notFoundMarker - a marker object indicating that the object corresponding to a key was not found

Returns:

an array of objects from this dictionary that correspond to each element of keys

isEqualToDictionary

public boolean isEqualToDictionary(NSDictionary otherDictionary)

Provided for backward compatibility. Use equals instead.

Parameters:

otherDictionary - the dictionary to compare this one to

Returns:

true if both the input dictionary and the this dictionary are equivalent, else false

See Also:

NSDictionary.equals(java.lang.Object)

equals

public boolean equals(Object object)

Compares this dictionary to object. If object is an instanceof NSDictionary and the contents of object are equal to these contents, this method returns true. If not, it returns false.

Two dictionaries have equal contents if they each hold the same number of entries and, for each key, the corresponding value objects in each dictionary satisfy the equals test. Note, this method does not adhere to the java.util.Map specification for equals and entrySets cannot Be compared to each other.

Specified by:

equals in interface Map

Overrides:

equals in class Object

Parameters:

object - the object to compare this dictionary against

Returns:

true if this dictionary is equivalent to object, else false

See Also:

Object.equals(java.lang.Object)

allKeys

public NSArray allKeys()

The order of the elements in the returned array is not defined.

Returns:

a new array containing the dictionary's keys or an empty array if the dictionary has no entries

See Also:

NSDictionary.allValues(), NSDictionary.allKeysForObject(java.lang.Object), NSDictionary.keyEnumerator()

allValues

public NSArray allValues()

The order of the values in the array is not defined.

Returns:

a new array containing the dictionary's values, or an empty array if the dictionary has no entries

See Also:

NSDictionary.allKeys(), NSDictionary.objectEnumerator()

keyEnumerator

public Enumeration keyEnumerator()

This method provides a java.util.Enumeration which can be used to access each key in this dictionary.

        <blockquote>

        java.util.Enumeration enumerator = myDict.keyEnumerator();
        while (enumerator.hasMoreElements()) {
          Object anObject = enumerator.nextElement();
          //code to act on each element
        }

        </blockquote>
 

When this method is used with mutable subclasses of NSDictionary, your code shouldn't modify the entries during enumeration. If you intend to modify the entries, use the allKeys method to create a "snapshot" of the dictionary's keys. Then use this snapshot to traverse the entries, modifying them along the way.

Note that the objectEnumerator method provides a convenient way to access each value in the dictionary.

Returns:

a java.util.Enumeration object that lets you access each key in the dictionary

See Also:

NSDictionary.allKeys(), NSDictionary.allKeysForObject(java.lang.Object), NSDictionary.objectEnumerator()

objectEnumerator

public Enumeration objectEnumerator()

This method provides a java.util.Enumeration which can be used to access each value in this dictionary.

        <blockquote>

        java.util.Enumeration enumerator = myDict.objectEnumerator();
        while (enumerator.hasMoreElements()) {
          Object anObject = enumerator.nextElement();
          //code to act on each element
        }

        </blockquote>
 

When this method is used with mutable subclasses of NSDictionary, your code shouldn't modify the entries during enumeration. If you intend to modify the entries, use the allValues method to create a "snapshot" of the dictionary's values. Work from this snapshot to modify the values.

Returns:

an object that lets you access all the values in the dictionary

See Also:

NSDictionary.keyEnumerator(), NSDictionary.allValues()

valueForKey

public Object valueForKey(String key)

Conformance to NSKeyValueCoding. This method is similar to objectForKey. It provides an entry's value given its key, or null if no value is associated with key.

Additionally, all dictionaries have the keys "allValues", "allKeys", and "count" defined, which provide a result identical to the invocation of the method of that name on this dictionary. If the dictionary contains an actual key which conflicts with these special keys, the real key trumps the computation. For example, if a dictionary has the key-value pair "count"-"dog" valueForKey will return "dog" instead of the result of the count method.

Specified by:

valueForKey in interface NSKeyValueCoding

Parameters:

key - the key to be searched for

Returns:

the value of the entry, or null if the key is not found

See Also:

NSDictionary.objectForKey(java.lang.Object), NSKeyValueCoding.valueForKey(java.lang.String), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String)

takeValueForKey

public void takeValueForKey(Object value,
                            String key)

Conformance to NSKeyValueCoding. Since NSDictionaries are immutable, this method simply throws an IllegalStateException.

Specified by:

takeValueForKey in interface NSKeyValueCoding

Parameters:

value - the input object

key - the key corresponding to the object

Throws:

java.lang.IllegalStateException

See Also:

NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String), NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String)

valueForKeyPath

public Object valueForKeyPath(String keyPath)

Conformance to NSKeyValueCodingAdditions. If the keyPath exists as a distinct key in the dictionary, this method returns the corresponding object in the dictionary by invoking objectForKey. Otherwise, it recursively invokes valueForKey for each segment of the keyPath on the result of the previous segment.

Specified by:

valueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

keyPath - the key path of the object

Returns:

the object corresponding to keypath

See Also:

NSDictionary.objectForKey(java.lang.Object), NSKeyValueCodingAdditions.valueForKeyPath(java.lang.String), NSKeyValueCoding.valueForKey(java.lang.String)

takeValueForKeyPath

public void takeValueForKeyPath(Object value,
                                String keyPath)

Conformance to NSKeyValueCodingAdditions. Since NSDictionaries are immutable, this method simply throws an IllegalStateException.

Specified by:

takeValueForKeyPath in interface NSKeyValueCodingAdditions

Parameters:

value - the input object

keyPath - the path of the input object

Throws:

java.lang.IllegalStateException

See Also:

NSKeyValueCodingAdditions.takeValueForKeyPath(java.lang.Object, java.lang.String), NSKeyValueCoding.takeValueForKey(java.lang.Object, java.lang.String)

classForCoder

public Class classForCoder()

Conformance to NSCoding. See the method description of classForCoder in the interface specification for NSCoding.

Specified by:

classForCoder in interface NSCoding

Returns:

NSDictionary.class

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSDictionary from the data in coder.

Parameters:

coder - the input coder

Returns:

a dictionary with the data in the input array

See Also:

NSCoding

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Description copied from interface: NSCoding

Encodes the receiver using coder. Object type information along with an object's data is stored.

Specified by:

encodeWithCoder in interface NSCoding

Parameters:

coder - an NSCoder object that will be used to encode object of classes that implement this interface

See Also:

NSCoder

hashCode

public int hashCode()

Specified by:

hashCode in interface Map

Overrides:

hashCode in class Object

Returns:

an appropriate hash code useful for storing the receiver in a hash-based data structure

See Also:

Object.hashCode()

clone

public Object clone()

Returns a copy (an NSDictionary object) of this dictionary. Since NSDictionaries are immutable, there's no need to make an actual copy.

Overrides:

clone in class Object

Returns:

this

See Also:

NSDictionary.mutableClone(), NSDictionary.immutableClone(), Object.clone()

immutableClone

public NSDictionary immutableClone()

Since NSDictionaries are immutable, there's no need to make an actual copy.

Returns:

an immutable copy of this dictionary

See Also:

NSDictionary.mutableClone(), NSDictionary.clone()

mutableClone

public NSMutableDictionary mutableClone()

Returns:

a new NSMutableDictionary with the same keys and value objects as the receiver

See Also:

NSDictionary.immutableClone(), NSDictionary.clone()

toString

public String toString()

Overrides:

toString in class Object

Returns:

a string representation each key-value pair.

emptyDictionary

public static final NSDictionary emptyDictionary()

Returns the empty NSDictionary (immutable). This map is serializable.

This example illustrates the type-safe way to obtain an empty dictionary:

 Map<String>      s       = NSDictionary.emptyArray();
 

Implementation note: Implementations of this method need not create a separate NSDictionary object for each call. Using this method is likely to have comparable cost to using the like-named field. (Unlike this method, the field does not provide type safety.)

Since:

5.4

See Also:

NSDictionary.EmptyDictionary

size

public int size()

Specified by:

size in interface Map

Since:

5.3

See Also:

Map.size()

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map

Since:

5.3

See Also:

Map.isEmpty()

containsKey

public boolean containsKey(Object key)

NSDictionaries do not allow null keys which differs from the java.util.Map specification. We return false for the key = null case

Specified by:

containsKey in interface Map

Since:

5.3

See Also:

Map.containsKey(java.lang.Object)

containsValue

public boolean containsValue(Object value)

NSDictionaries do not allow for null values which differs from the java.util.Map specification. We return false for the value = null case.

Specified by:

containsValue in interface Map

Since:

5.3

See Also:

Map.containsValue(java.lang.Object)

get

public Object get(Object key)

Conforms to NSDictionary.objectForKey() specification.

Specified by:

get in interface Map

Since:

5.3

See Also:

Map.get(java.lang.Object)

put

public Object put(Object key,
                  Object value)

Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:

put in interface Map

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Map.put(K, V)

remove

public Object remove(Object key)

Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:

remove in interface Map

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Map.remove(java.lang.Object)

putAll

public void putAll(Map t)

Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:

putAll in interface Map

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Map.putAll(java.util.Map)

clear

public void clear()

Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:

clear in interface Map

Throws:

UnsupportedOperationException

Since:

5.3

See Also:

Map.clear()

keySet

public Set keySet()

Specified by:

keySet in interface Map

Since:

5.3

See Also:

Map.keySet()

values

public Collection values()

Warning: NSDictionaries are immutable and therefore this method does not adhere to the Java specification.

Specified by:

values in interface Map

Returns:

NSArray - array of values

Since:

5.3

See Also:

Map.values()

entrySet

public Set entrySet()

Specified by:

entrySet in interface Map

Since:

5.3

See Also:

Map.keySet()