com.jadeworld.jade.rootschema
Class Collection<M>

java.lang.Object
  com.jadeworld.jade.rootschema.Object
      com.jadeworld.jade.rootschema.Collection<M>

All Implemented Interfaces:

java.lang.Iterable<M>, java.util.Collection<M>

Direct Known Subclasses:

Array, Dictionary, ObjectSet, VirtualColl

public abstract class Collection<M>
extends Object
implements java.util.Collection<M>

The base class for all JADE collections. All collections of objects inherit from this class. JADE primitive arrays become ArrayLists of primitives.

This class implements the java.util.Collection interface, so that all JADE collections can be used as if they were Java collections, subject to some differences in the underlying implementations.

The JADE Collection class also implements extra methods to expose the additional JADE functionality.

Field Summary

Fields inherited from class com.jadeworld.jade.rootschema.Object

oid

Constructor Summary

Collection()

Method Summary

boolean	add(M element) Adds the object specified in the element parameter to the collection.
boolean	addAll(java.util.Collection<? extends M> c) Adds all of the items in the specified collection to this collection.
void	clear() Removes all entries from this collection.
boolean	contains(java.lang.Object element) Returns true if the collection contains the object specified in the element parameter.
boolean	containsAll(java.util.Collection<?> c) Returns true if this collection already contains all items in the given collection.
void	copy(ByRef<Collection> toColl) Copies entries from the receiver collection to a compatible collection passed as the toColl parameter.
int	countOf(java.lang.Object o) Returns the number of times the entry specified in the parameter occurs in this collection.
Iterator<M>	createIterator() Creates a heavyweight JADE iterator, which implements the java.util.Iterator interface.
void	deleteIfEmpty() Deletes an empty shared or exclusive collection.
M	first() Returns a reference to the first entry in this collection.
java.lang.Object	getOwner() Returns a reference to the object that is the owner, or parent, of the collection.
void	getStatistics(ByRef<JadeDynamicObject> jdoRef) Analyzes the collection and returns structural statistics in the attributes of a JadeDynamicObject, representing collection statistics.
int	indexOf(java.lang.Object o) Returns the index of the entry specified in the parameter if it exists in the collection or it returns zero if it does not exist.
void	instantiate() Ensures that the collection is created before it is used..
boolean	isEmpty() Returns true if there are no elements in the collection.
java.util.Iterator<M>	iterator() Creates a lightweight JADE iterator, which implements the java.util.Iterator interface.
M	last() Returns a reference to the last entry in this collection.
int	maxSize() Returns the maximum number of entries that a collection can contain.
void	purge() Deletes all objects in a collection and clears the collection; that is, size = 0.
boolean	remove(java.lang.Object element) Removes an item from a collection.
boolean	removeAll(java.util.Collection<?> c) Removes all of the items in the current collection that are also in the given collection.
boolean	retainAll(java.util.Collection c) Retains all of the items in the current collection which are also in the specified collection.
void	setBlockSize(int blockSize) Enables you to specify or change the block size of the receiver in terms of entries in each block.
int	size() Returns the size of the collection.
java.lang.Object[]	toArray() Returns an Object array containing all of this collection's items in the order specified by the collection iterator.
java.lang.Object[]	toArray(java.lang.Object[] a) Not yet implemented
java.lang.String	toString() Return the value when an object instance is displayed.

Methods inherited from class com.jadeworld.jade.rootschema.Object

changeObjectVolatility, creationTime, edition, equals, exclusiveLock, getClassNumberForObject, getInstanceIdForObject, getLockStatus, getName, getObjectStringForObject, getObjectVolatility, getOidString, getOidStringForObject, getPropertyValue, hashCode, hasMembers, isImportedObject, isKindOf, isLockedByMe, isObjectFrozen, isObjectNonSharedTransient, isObjectPersistent, isObjectSharedTransient, isObjectStable, isObjectTransient, isObjectVolatile, isSharedTransient, isSystemObject, isTransient, latestEdition, lock, makeObjectFrozen, makeObjectStable, makeObjectVolatile, reserveLock, sdeCauseEvent, sdsCauseEvent, setPropertyValue, sharedLock, tryLock, unlock, updateObjectEdition

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, hashCode

Constructor Detail

Collection

public Collection()

Method Detail

toString

public java.lang.String toString()

Return the value when an object instance is displayed.

Overrides:

toString in class Object

Returns:

Class name and oid value.

createIterator

public Iterator<M> createIterator()

Creates a heavyweight JADE iterator, which implements the java.util.Iterator interface.

Returns:

An Iterator instance associated with this collection,

iterator

public java.util.Iterator<M> iterator()

Creates a lightweight JADE iterator, which implements the java.util.Iterator interface.

Specified by:

iterator in interface java.lang.Iterable<M>

Specified by:

iterator in interface java.util.Collection<M>

Returns:

An Iterator instance associated with this collection.

size

public int size()

Returns the size of the collection.

Specified by:

size in interface java.util.Collection<M>

Returns:

The number of elements in the collection.

isEmpty

public boolean isEmpty()

Returns true if there are no elements in the collection.

Specified by:

isEmpty in interface java.util.Collection<M>

Returns:

true if the collection is empty, otherwise false.

contains

public boolean contains(java.lang.Object element)

Returns true if the collection contains the object specified in the element parameter. This method returns false if a null reference is passed to the value parameter.

Specified by:

contains in interface java.util.Collection<M>

Parameters:

element - The object to check for existence in the collection.

Returns:

true if the element is found in the collection.

add

public boolean add(M element)

Adds the object specified in the element parameter to the collection.

Specified by:

add in interface java.util.Collection<M>

Parameters:

element - the object is to add to the collection

Returns:

true if the object was added successfully.

remove

public boolean remove(java.lang.Object element)

Removes an item from a collection. If the collection does not contain the specified item, an exception is raised.

Specified by:

remove in interface java.util.Collection<M>

Parameters:

element - The object to remove from the collection.

Returns:

true if the object was removed successfully.

containsAll

public boolean containsAll(java.util.Collection<?> c)

Returns true if this collection already contains all items in the given collection.

Specified by:

containsAll in interface java.util.Collection<M>

Parameters:

c - The collection whose items are to be checked against the current collection.

Returns:

true if the current collection contains all items of the parameter collection.

addAll

public boolean addAll(java.util.Collection<? extends M> c)

Adds all of the items in the specified collection to this collection.

Specified by:

addAll in interface java.util.Collection<M>

Parameters:

c - The collection whose items are to be added.

Returns:

true if the collection changes after this operation.

removeAll

public boolean removeAll(java.util.Collection<?> c)

Removes all of the items in the current collection that are also in the given collection. NOT yet implemented

Specified by:

removeAll in interface java.util.Collection<M>

Parameters:

c - The collection whose items are to be removed.

Returns:

true if the collection changes after this operation.

retainAll

public boolean retainAll(java.util.Collection c)

Retains all of the items in the current collection which are also in the specified collection. NOT yet implemented

Specified by:

retainAll in interface java.util.Collection<M>

Parameters:

c - The collection whose items are to be removed.

Returns:

true if the collection changes after this operation.

clear

public void clear()

Removes all entries from this collection. The entries are not deleted; they are simply no longer in the collection.

Specified by:

clear in interface java.util.Collection<M>

toArray

public java.lang.Object[] toArray()

Returns an Object array containing all of this collection's items in the order specified by the collection iterator.

Specified by:

toArray in interface java.util.Collection<M>

Returns:

The collection as an Object array.

toArray

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

Not yet implemented

Specified by:

toArray in interface java.util.Collection<M>

copy

public void copy(ByRef<Collection> toColl)

Copies entries from the receiver collection to a compatible collection passed as the toColl parameter. In this case, compatible means that the memberships of the receiver and destination collections are type-compatible. For example, the copy method can be used to copy entries from a dictionary of employees to an array of objects, as shown in the following example.

EntityAccess.createAsTransient(personArray);
ByRef collRef = ByRef.io(personArray); dept.getAllEmployees().copy(collRef);

personArray = collRef.get();

Note By default, entries copied from the receiver collection are added to entries that already exist in the collection to which you copy them.
JADE-only method.

Parameters:

toColl - The collection to which the contents of the current collection are to be copied..

countOf

public int countOf(java.lang.Object o)

Returns the number of times the entry specified in the parameter occurs in this collection.
JADE-only method.

Parameters:

o - The object to search for.

Returns:

The number of times this object occurs.

deleteIfEmpty

public void deleteIfEmpty()

Deletes an empty shared or exclusive collection. If the collection is not empty, calling this method raises exception 1320 (Operation invalid - collection not empty). Call the isEmpty() method to determine if a collection is empty.

Caution Although you can use this method with any exclusive collection, it un-instantiates (deletes) the collection if it has no members. You should therefore take care to ensure that old copies of the exclusive collection are not left in node caches.
If the collection is repopulated, it is instantiated starting with edition 1. This can match an old copy in cache, which could then be regarded as current.
JADE-only method.

first

public M first()

Returns a reference to the first entry in this collection. Null is returned if the collection is empty.
JADE-only method.

Returns:

The object which is the first entry in the collection.

getOwner

public java.lang.Object getOwner()

Returns a reference to the object that is the owner, or parent, of the collection. This method returns null if the object is not an exclusive collection.

getStatistics

public void getStatistics(ByRef<JadeDynamicObject> jdoRef)

Analyzes the collection and returns structural statistics in the attributes of a JadeDynamicObject, representing collection statistics.

The attributes of a collection statistics dynamic object are defined and interpreted as follows.

Attribute Description

 blockSize Entries per block

 keyLength Size of the key in bytes (oid (6) for Set classes and Integer (4) for Array classes)

 entrySize Size of each collection entry in bytes

 size Number of entries in the collection (that is, the size of the collection itself)

 blockCount Total number of blocks in the collection

 height Number of levels in the collection (always 1 for Array classes)

 minEntries Minimum number of entries found in any block

 maxEntries Maximum number of entries found in any block

 avgEntries Average number of entries in collection blocks

 loadFactor Actual average percent loading of collection blocks (entries for each block)

 To compute the block size in bytes, multiply the blockSize attribute by the entrySize attribute. The
 maximum collection block size for a collection is 256K bytes

JADE-only method.

indexOf

public int indexOf(java.lang.Object o)

Returns the index of the entry specified in the parameter if it exists in the collection or it returns zero if it does not exist. If the specified value occurs more than once in the collection, the index of the first occurrence is returned.
JADE-only method.

Parameters:

o - The object to search for.

Returns:

The index of the (first) occurence in the collection.

instantiate

public void instantiate()

Ensures that the collection is created before it is used..

Note This method applies only to exclusive collections.
JADE-only method.

last

public M last()

Returns a reference to the last entry in this collection. Null is returned if the collection is empty.
JADE-only method.

Returns:

The object that is the last entry in the collection.

maxSize

public int maxSize()

Returns the maximum number of entries that a collection can contain.
JADE-only method.

Returns:

The maximum collection size.

purge

public void purge()

Deletes all objects in a collection and clears the collection; that is, size = 0.
JADE-only method.

Caution: The objects that are removed are physically deleted.

The purge operation ignores object not found exceptions, which enables you to fix manually maintained collections that have references to objects that are now deleted.

setBlockSize

public void setBlockSize(int blockSize)

Enables you to specify or change the block size of the receiver in terms of entries in each block. When you use this method to change the collection block size, all collection blocks for the receiver are created with the specified size. For details about the behavior of and tuning collections, see Chapter 4 of the JADE Developers Reference.
A physical upper limit is enforced. (The maximum collection block size for a collection is 256K bytes; that is, the value defined by the MaximumCollectionBlockSize global constant in the SystemLimits category). If the value of entries per block multiplied by the collection entry size causes the actual block size to exceed the JADE limit, an exception is raised.
If this method is invoked on a populated collection and the block size differs from that already in use by the receiver, an automatic upgrade is triggered, which restructures the collection to use the new size.

Note<.b> The time taken to reblock a collection increases with the collection size and could be quite lengthy for large collections. This reblock operation is similar to the type of upgrade that can occur during a reorganization, and the collection remains inaccessible until the process has completed.