com.triactive.jdo.sco
Class HashSet

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractSet
          java.util.HashSet
              com.triactive.jdo.sco.HashSet

All Implemented Interfaces:

java.lang.Cloneable, java.util.Collection, Deleteable, Queryable, SCO, SCOCollection, java.io.Serializable, java.util.Set

public class HashSet

extends java.util.HashSet

implements SCOCollection, java.lang.Cloneable, Queryable, Deleteable

A mutable second-class HashSet object.

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

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

While the owner/set is transient:

1. Elements are restricted to be of the designated element type.
2. All write operations cause the corresponding field in the owner to be marked dirty.

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

1. The contents of the set 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 (size(), isEmpty(), contains()) "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 set. All other read operations by nature must access the entire set 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. With the exception of retainAll(), 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 set is persistent.

The set 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 Set field refers to it) transitions to a unmanaged state. When a disconnect occurs the object subsequently behaves as a normal HashSet. 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

HashSet(java.lang.Object owner, java.lang.String fieldName, PersistentSet backing)
Constructs an SCO HashSet representing an existing persistent set.

HashSet(java.lang.Object owner, java.lang.String fieldName, PersistentSet backing, java.util.Collection value)
Constructs an SCO HashSet having the specified initial contents.

Method Summary

boolean	add(java.lang.Object o)
boolean	addAll(java.util.Collection c)
boolean	allowsNulls() Indicates whether or not this collection allows null elements.
boolean	alreadyDistinct() Indicates whether or not the candidate collection contains a set of distinct (unique) objects.
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	contains(java.lang.Object o)
boolean	containsAll(java.util.Collection c)
void	deletePersistentAll() Deletes all instances in this collection from the data store.
boolean	equals(java.lang.Object o)
java.lang.Class	getCandidateClass() Returns the default class of candidate objects contained in this queryable collection.
java.lang.Class	getElementType() Returns the type of elements in this collection.
java.lang.String	getFieldName() Returns the field name in the owner object.
java.lang.Object	getOwner() Returns the owner object of the SCO instance.
int	hashCode()
boolean	isEmpty()
java.util.Iterator	iterator()
void	makeDirty() Marks this object dirty.
SqlExpression	newQueryStatement(java.lang.Class candidateClass) Creates a prototypical query statement over the underlying collection, pre-filtered to include only objects of the specified class.
boolean	remove(java.lang.Object o)
boolean	removeAll(java.util.Collection c)
boolean	retainAll(java.util.Collection c)
int	size()
java.lang.Object[]	toArray()
java.lang.Object[]	toArray(java.lang.Object[] a)
java.lang.String	toString()
void	unsetOwner() Disconnects this object from its owner.
protected java.lang.Object	writeReplace() Replaces the object to be serialized with a java.util.HashSet object.

Methods inherited from class java.lang.Object

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

Constructor Detail

HashSet

public HashSet(java.lang.Object owner,
               java.lang.String fieldName,
               PersistentSet backing)

Constructs an SCO HashSet representing an existing persistent set. The set'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 set.

HashSet

public HashSet(java.lang.Object owner,
               java.lang.String fieldName,
               PersistentSet backing,
               java.util.Collection value)

Constructs an SCO HashSet 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 set 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 set.

value - The initial contents of the set.

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.

getElementType

public java.lang.Class getElementType()

Description copied from interface: SCOCollection

Returns the type of elements in this collection.

Specified by:

getElementType in interface SCOCollection

Returns:

The type of elements in this collection.

allowsNulls

public boolean allowsNulls()

Description copied from interface: SCOCollection

Indicates whether or not this collection allows null elements.

Specified by:

allowsNulls in interface SCOCollection

Returns:

true if null elements 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

getCandidateClass

public java.lang.Class getCandidateClass()

Description copied from interface: Queryable

Returns the default class of candidate objects contained in this queryable collection.

Specified by:

getCandidateClass in interface Queryable

Returns:

The default candidate class.

alreadyDistinct

public boolean alreadyDistinct()

Description copied from interface: Queryable

Indicates whether or not the candidate collection contains a set of distinct (unique) objects.

Specified by:

alreadyDistinct in interface Queryable

Returns:

true if the candidate objects are all unique, false if there may be duplicates.

newQueryStatement

public SqlExpression newQueryStatement(java.lang.Class candidateClass)

Description copied from interface: Queryable

Creates a prototypical query statement over the underlying collection, pre-filtered to include only objects of the specified class. The return value is an SQL expression within the query statement representing the candidate objects. No result columns have been selected in the statement.

Specified by:

newQueryStatement in interface Queryable

Parameters:

candidateClass - The class of objects to query over.

Returns:

An SQL expression within the new prototypical query statement which represents the candidate objects.

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

iterator

public java.util.Iterator iterator()

Specified by:

iterator in interface java.util.Collection

size

public int size()

Specified by:

size in interface java.util.Collection

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Collection

contains

public boolean contains(java.lang.Object o)

Specified by:

contains in interface java.util.Collection

add

public boolean add(java.lang.Object o)

Specified by:

add in interface java.util.Collection

remove

public boolean remove(java.lang.Object o)

Specified by:

remove in interface java.util.Collection

clear

public void clear()

Specified by:

clear in interface java.util.Collection

deletePersistentAll

public void deletePersistentAll()

Description copied from interface: Deleteable

Deletes all instances in this collection from the data store.

Specified by:

deletePersistentAll in interface Deleteable

containsAll

public boolean containsAll(java.util.Collection c)

Specified by:

containsAll in interface java.util.Collection

addAll

public boolean addAll(java.util.Collection c)

Specified by:

addAll in interface java.util.Collection

removeAll

public boolean removeAll(java.util.Collection c)

Specified by:

removeAll in interface java.util.Collection

retainAll

public boolean retainAll(java.util.Collection c)

Specified by:

retainAll in interface java.util.Collection

toArray

public java.lang.Object[] toArray()

Specified by:

toArray in interface java.util.Collection

toArray

public java.lang.Object[] toArray(java.lang.Object[] a)

Specified by:

toArray in interface java.util.Collection

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Collection

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Collection

toString

public java.lang.String toString()

writeReplace

protected java.lang.Object writeReplace()

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

Returns:

The HashSet to be serialized instead of this object.