com.triactive.jdo.sco
Class HashMap

java.lang.Object
  java.util.AbstractMap
      java.util.HashMap
          com.triactive.jdo.sco.HashMap

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map, SCO, SCOMap, java.io.Serializable

public class HashMap

extends java.util.HashMap

implements SCOMap, java.lang.Cloneable

A mutable second-class HashMap object.

SCO fields declared as type java.util.Map or java.util.HashMap are populated with objects of this type whenever the owning object is actively being managed by a state manager.

While an SCO HashMap is owned it is considered either transient or persistent according to whether its owner is in a transient or persistent state.

While the owner/map is transient:

1. Entries are restricted to be of the designated key & value type.
2. All write operations cause the corresponding field in the owner to be marked dirty.

In addition to the above, while the owner/map is persistent:

1. The contents of the map may or may not be fully loaded in memory. If they are loaded within a transaction they are considered "up-to-date" only until the next update of the data store.
2. Some read operations (get(), size(), isEmpty(), containsKey(), containsValue()) "pass through" directly to the database if the memory contents are not up-to-date. This avoids an expensive load from the data store for operations that don't necessarily involve the entire map. All other read operations by nature must access the entire map and so they always load the contents, or reload them if they are not up-to-date.
3. All write operations always pass through directly to the database, although the memory copy is also updated. No write operation requires the contents to be loaded.

An instance of this class is always associated with a backing store, although the store is only used when the map is persistent.

The map disconnects from its owner when unsetOwner() is called. This occurs automatically in a variety of scenarios, such as when the object is cloned or when its owning object (the one whose Map field refers to it) transitions to a unmanaged state. When a disconnect occurs the object subsequently behaves as a normal HashMap. Subsequent changes affect only the memory contents. Once disconnected from its owner an instance can never be reconnected.

Author:

Mike Martin

See Also:

Serialized Form

Constructor Summary

HashMap(java.lang.Object owner, java.lang.String fieldName, PersistentMap backing)
Constructs an SCO HashMap representing an existing persistent map.

HashMap(java.lang.Object owner, java.lang.String fieldName, PersistentMap backing, java.util.Map value)
Constructs an SCO HashMap having the specified initial contents.

Method Summary

boolean	allowsNullValues() Indicates whether or not this map allows null values.
void	applyUpdates() Called to indicate that the owning object is being made persistent, or that the persistent state of this field is being updated.
void	clear()
java.lang.Object	clone() Creates and returns a copy of this object.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
java.util.Set	entrySet()
boolean	equals(java.lang.Object o)
java.lang.Object	get(java.lang.Object key)
java.lang.String	getFieldName() Returns the field name in the owner object.
java.lang.Class	getKeyType() Returns the type of keys in this map.
java.lang.Object	getOwner() Returns the owner object of the SCO instance.
java.lang.Class	getValueType() Returns the type of values in this map.
int	hashCode()
boolean	isEmpty()
java.util.Set	keySet()
void	makeDirty() Marks this object dirty.
java.lang.Object	put(java.lang.Object key, java.lang.Object value)
void	putAll(java.util.Map m)
java.lang.Object	remove(java.lang.Object key)
int	size()
java.lang.String	toString()
void	unsetOwner() Disconnects this object from its owner.
java.util.Collection	values()
protected java.lang.Object	writeReplace() Replaces the object to be serialized with a java.util.HashMap object.

Methods inherited from class java.lang.Object

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

Constructor Detail

HashMap

public HashMap(java.lang.Object owner,
               java.lang.String fieldName,
               PersistentMap backing)

Constructs an SCO HashMap representing an existing persistent map. The map's contents are initially not loaded.

Parameters:

owner - The object that owns this second-class object.

fieldName - The fieldName in the owning object.

backing - The backing store for this map.

HashMap

public HashMap(java.lang.Object owner,
               java.lang.String fieldName,
               PersistentMap backing,
               java.util.Map value)

Constructs an SCO HashMap having the specified initial contents.

If the owning object is already persistent it is assumed its field is being assigned an entirely new value. The existing map contents are cleared in the data store and the new contents are added.

Parameters:

owner - The object that owns this second-class object.

fieldName - The fieldName in the owning object.

backing - The backing store for this map.

value - The initial contents of the map.

Method Detail

getOwner

public java.lang.Object getOwner()

Description copied from interface: SCO

Returns the owner object of the SCO instance.

Specified by:

getOwner in interface SCO

Returns:

The owner object or null if currently unowned.

getFieldName

public java.lang.String getFieldName()

Description copied from interface: SCO

Returns the field name in the owner object.

Specified by:

getFieldName in interface SCO

Returns:

The field name or null if currently unowned.

getKeyType

public java.lang.Class getKeyType()

Description copied from interface: SCOMap

Returns the type of keys in this map.

Specified by:

getKeyType in interface SCOMap

Returns:

The type of keys in this map.

getValueType

public java.lang.Class getValueType()

Description copied from interface: SCOMap

Returns the type of values in this map.

Specified by:

getValueType in interface SCOMap

Returns:

The type of values in this map.

allowsNullValues

public boolean allowsNullValues()

Description copied from interface: SCOMap

Indicates whether or not this map allows null values.

Specified by:

allowsNullValues in interface SCOMap

Returns:

true if null values are allowed, false otherwise.

makeDirty

public void makeDirty()

Description copied from interface: SCO

Marks this object dirty. If the SCO is currently owned this method should mark the corresponding field in the owning object as dirty.

Specified by:

makeDirty in interface SCO

applyUpdates

public void applyUpdates()

Description copied from interface: SCO

Called to indicate that the owning object is being made persistent, or that the persistent state of this field is being updated.

Specified by:

applyUpdates in interface SCO

unsetOwner

public void unsetOwner()

Description copied from interface: SCO

Disconnects this object from its owner.

Specified by:

unsetOwner in interface SCO

clone

public java.lang.Object clone()

Creates and returns a copy of this object.

Mutable second-class Objects are required to provide a public clone method in order to allow for copying PersistenceCapable objects. In contrast to Object.clone(), this method must not throw a CloneNotSupportedException.

Specified by:

clone in interface SCO

size

public int size()

Specified by:

size in interface java.util.Map

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map

get

public java.lang.Object get(java.lang.Object key)

Specified by:

get in interface java.util.Map

put

public java.lang.Object put(java.lang.Object key,
                            java.lang.Object value)

Specified by:

put in interface java.util.Map

putAll

public void putAll(java.util.Map m)

Specified by:

putAll in interface java.util.Map

remove

public java.lang.Object remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map

clear

public void clear()

Specified by:

clear in interface java.util.Map

keySet

public java.util.Set keySet()

Specified by:

keySet in interface java.util.Map

values

public java.util.Collection values()

Specified by:

values in interface java.util.Map

entrySet

public java.util.Set entrySet()

Specified by:

entrySet in interface java.util.Map

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Map

toString

public java.lang.String toString()

writeReplace

protected java.lang.Object writeReplace()

Replaces the object to be serialized with a java.util.HashMap object. Invoked by the serialization mechanism to obtain an alternative object to be used when writing an object to the stream.

Returns:

The HashMap to be serialized instead of this object.