Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.util.Metavector

java.lang.Object
  |
  +--ncsa.horizon.util.Metavector

public class Metavector

extends java.lang.Object

implements java.lang.Cloneable, java.io.Serializable

a container for holding an array of metadata. This looks and behaves very much like the Vector object (although it is not a subclass of Vector). It is intended (but not enforced or required) that all the array members have the same type.

An important feature of this container is its support for a default values. This support differentiates a Metavector from a regular Vector in the following ways:

• default values (stored as an internal Metavector object) are set during construction and cannot be publicly overwritten.
• if a default value is not provide, the default value is null
• Array values may be set that override the default; however, when values are removed or erased, the default remains in place.
• if the user requests the value of an index that is out of range, null is returned. (No exception is thrown, and the size of the array does not change.)
• the size of the array cannot be reduced to less than the size default array.
• values at indices less than the size of the default array cannot be shifted via a request to insert or remove a value.

The internally stored default metavector provides a way for managers of metadata to protect their data from updates by other objects. If a metadata manager has a Metavector it wants other objects to read from but not write into, it can create a new Metavector object that has the original as the default. The other users of the new Metavector can then read the elements and even override them without affecting the original Metavector object.

One other feature of the support for default values is that it allows the originator of Metavector (the object that has a reference to the default Metavector) to update the defaults after the Metavector has been created and passed on. Such changes would be seen by those objects that have not overriden the defaults. Client objects that prefer that their copy of the Metavector not be connected the originator in this way can "detach" it via the detach() method. Other methods are provided for obtaining "detached" copies of the data, including copyInto(Object[]), copyIntoVector(), detachedClone(), and cloneDefaults(). (Note that the standard clone() produces a Metavector whose defaults are "attached" to the same object as the original.)

One should note that the defaults protection only applies to the internal default Metavector container itself, not its elements. That is, the value returned by elementAt(int) is the original version of the datum and not a copy. Thus, there may be any number of references to the datum held by other objects. (The datum is protected only if it is of a type that is not internally editable. For example, the value of an Integer or String object cannot be updated; however, if the datum is of type Stack, the data internal to that Stack is not protected from updates.) An exception to this is when the value is obtained from the default list and is of type Metavector or Metadata; in this case, the meta-container is placed as the default list in a new meta-container before being passed on.

See Also:

Serialized Form

Field Summary

int	capacityIncrement amount to increase the capacity of the internal array when additional data slots are needed.
Metavector	defaults The default values
int	elementCount The number of elements in the array
java.lang.Object[]	elementData The buffer where elements are stored.
boolean	executeRunners true if Runnable objects should be executed to obtain values for requested metadata when available.

Constructor Summary

Metavector(Metavector defaults, int initialCapacity, int capacityIncrement)
Constructs a metavector with specified default values, storage capacity and capacity increment.

Metavector(int initialCapacity, int capacityIncrement)
Constructs an empty vector with the specified storage capacity and the specified capacityIncrement but with no default values.

Metavector(int initialCapacity)
Constructs a metavector with the specified storage capacity but with no default values

Metavector(Metavector defaults, int initialCapacity)
Constructs a metavector with the specified storage capacity.

Metavector(Metavector defaults)
Constructs a metavector with the specified defaults

Metavector()
Constructs a metavector with no default values.

Method Summary

void	addElement(java.lang.Object obj) Adds the specified object as the last element of the vector.
int	capacity() Returns the current capacity of the vector.
Metavector	cloneDefaults() clone the defaults metavector.
java.lang.Object	clone() Clones this metavector.
boolean	contains(java.lang.Object elem) Returns true if the specified object is a value of the collection.
void	copyInto(java.lang.Object[] anArray) Copies the elements of this vector into the specified array.
void	copyInto(Metavector that) Copies the elements of this Metavector into another Metavector
java.util.Vector	copyIntoVector() Create a java.util.
Metavector	deepClone() create a semi-deep clone.
int	defaultSize() Returns the number of elements in the vector.
Metavector	detachedClone() Like clone(), except that a copy of the defaults metavector is also made.
void	detach() replace the internal default Metavector with a copy, detaching control of the defaults from the originator of this Metavector.
java.lang.Object	elementAt(int index) Returns the element at the specified index.
java.lang.Object	elementAt(int index, java.lang.Object defaultValue) Returns the element at the specified index.
java.util.Enumeration	elements() Returns an enumeration of the elements.
void	ensureCapacity(int minCapacity) Ensures that the vector has at least the specified capacity.
void	eraseElementAt(int index) erases the current value of an element, returning it to its default value.
java.lang.Object	firstElement() Returns the first element of the sequence.
java.lang.Object	getMetadatum(int index, java.lang.String name) if the element at a specified index is a Metadata object, return the value of the metadatum given by the specified name; otherwise return null.
java.lang.Object	getMetadatum(int index, java.lang.String name, boolean doRun) if the element at a specified index is a Metadata object, return the value of the metadatum given by the specified name; otherwise return null.
int	indexOf(java.lang.Object elem) Searches for the specified object, starting from the first position and returns an index to it.
int	indexOf(java.lang.Object elem, int index) Searches for the specified object, starting at the specified position and returns an index to it.
boolean	insertElementAt(java.lang.Object obj, int index) Conditionally inserts the specified object as an element at the specified index.
java.lang.Object	lastElement() Returns the last element of the sequence.
int	lastIndexOf(java.lang.Object elem) Searches backwards for the specified object, starting from the last position and returns an index to it.
int	lastIndexOf(java.lang.Object elem, int index) Searches backwards for the specified object, starting from the specified position and returns an index to it.
static ValueAndStatus	parseOutElement(java.lang.String name) parse a metadatum name for a Metavector element reference and (optionally) a sub-metadatum name, assuming a form for the input string of "[n]" or "[n].subname".
void	removeAllElements() Revert the metavector to its fully default state.
boolean	removeElementAt(int index) Erases and (when possible) deletes the element at the specified index.
boolean	removeElement(java.lang.Object obj) Erases and (when possible) deletes the element from the vector.
void	setDefaults(Metavector to) Set the default Metavector of this Metavector object.
void	setElementAt(java.lang.Object obj, int index) Sets the element at the specified index to be the specified object, growing the array as necessary.
void	setSize(int newSize) Sets the size of the vector.
int	size() Returns the number of elements in the vector.
java.lang.String	toString() Converts the vector to a string.
void	trimToSize() Trims the vector's capacity down to size.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait

Field Detail

capacityIncrement

protected int capacityIncrement

amount to increase the capacity of the internal array when additional data slots are needed. If value is 0, then the capacity is double each time it is expanded.

elementCount

protected int elementCount

The number of elements in the array

elementData

protected java.lang.Object[] elementData

The buffer where elements are stored. The capacity of the container is given by the length of this array.

defaults

protected Metavector defaults

The default values

executeRunners

public boolean executeRunners

true if Runnable objects should be executed to obtain values for requested metadata when available. Note that this class does not support transparent execution of Metarunners saved elements of its array; this tag is only used by the getMetadatum() method.

Constructor Detail

Metavector

public Metavector(Metavector defaults,
                  int initialCapacity,
                  int capacityIncrement)

Constructs a metavector with specified default values, storage capacity and capacity increment.

Parameters:

defaults - Metavector containing default values

initialCapacity - the initial storage capacity of the vector

capacityIncrement - how much to increase the element's size by.

Metavector

public Metavector(int initialCapacity,
                  int capacityIncrement)

Constructs an empty vector with the specified storage capacity and the specified capacityIncrement but with no default values.

Parameters:

initialCapacity - the initial storage capacity of the vector

capacityIncrement - how much to increase the element's size by.

Metavector

public Metavector(int initialCapacity)

Constructs a metavector with the specified storage capacity but with no default values

Parameters:

initialCapacity - the initial storage capacity of the vector

Metavector

public Metavector(Metavector defaults,
                  int initialCapacity)

Constructs a metavector with the specified storage capacity.

Parameters:

defaults - Metavector containing default values

initialCapacity - the initial storage capacity of the vector

Metavector

public Metavector(Metavector defaults)

Constructs a metavector with the specified defaults

Parameters:

defaults - Metavector containing default values

initialCapacity - the initial storage capacity of the vector

Metavector

public Metavector()

Constructs a metavector with no default values.

Method Detail

size

public final int size()

Returns the number of elements in the vector. Note that this is not the same as the vector's capacity.

defaultSize

public final int defaultSize()

Returns the number of elements in the vector. Note that this is not the same as the vector's capacity.

capacity

public final int capacity()

Returns the current capacity of the vector.

trimToSize

public final void trimToSize()

Trims the vector's capacity down to size. Use this operation to minimize the storage of a vector. Subsequent insertions will cause reallocation.

ensureCapacity

public final void ensureCapacity(int minCapacity)

Ensures that the vector has at least the specified capacity.

Parameters:

minCapacity - the desired minimum capacity

setSize

public final void setSize(int newSize)

Sets the size of the vector. If the size shrinks, the extra elements (at the end of the vector) are lost; if the size increases, the new elements are set to null. The size cannot be shrunk to less than defaultSize().

Parameters:

newSize - the new size of the vector. If newSize is less than that returned by defaultSize(), the new size will be made equal to the default size.

elements

public final java.util.Enumeration elements()

Returns an enumeration of the elements. Use the Enumeration methods on the returned object to fetch the elements sequentially.

contains

public final boolean contains(java.lang.Object elem)

Returns true if the specified object is a value of the collection.

Parameters:

elem - the desired element

indexOf

public final int indexOf(java.lang.Object elem)

Searches for the specified object, starting from the first position and returns an index to it.

Parameters:

elem - the desired element

Returns:

the index of the element, or -1 if it was not found.

indexOf

public final int indexOf(java.lang.Object elem,
                         int index)

Searches for the specified object, starting at the specified position and returns an index to it.

Parameters:

elem - the desired element

index - the index where to start searching

Returns:

the index of the element, or -1 if it was not found.

lastIndexOf

public final int lastIndexOf(java.lang.Object elem)

Searches backwards for the specified object, starting from the last position and returns an index to it.

Parameters:

elem - the desired element

Returns:

the index of the element, or -1 if it was not found.

lastIndexOf

public final int lastIndexOf(java.lang.Object elem,
                             int index)

Searches backwards for the specified object, starting from the specified position and returns an index to it.

Parameters:

elem - the desired element

index - the index where to start searching

Returns:

the index of the element, or -1 if it was not found.

elementAt

public final java.lang.Object elementAt(int index)

Returns the element at the specified index.

Parameters:

index - the index of the desired element

elementAt

public final java.lang.Object elementAt(int index,
                              java.lang.Object defaultValue)

Returns the element at the specified index.

Parameters:

index - the index of the desired element

defaultValue - object to return if the index is out of range or if the primary value is null. This overrides the internally supported defaults.

parseOutElement

public static final ValueAndStatus parseOutElement(java.lang.String name)

parse a metadatum name for a Metavector element reference and (optionally) a sub-metadatum name, assuming a form for the input string of "[n]" or "[n].subname".

Returns:

ValueAndStatus the result of the parsing. The integer value found will appear in the status field and the sub-name String in the value field. If a element specification is not found, status will be < 0 and value will contain input string. If no subname was found, value will be null.

getMetadatum

public final java.lang.Object getMetadatum(int index,
                                 java.lang.String name)

if the element at a specified index is a Metadata object, return the value of the metadatum given by the specified name; otherwise return null. (This is equivalent to calling mv.getMetadatum(index, name, mv.executeRunners).)

getMetadatum

public final java.lang.Object getMetadatum(int index,
                                 java.lang.String name,
                                 boolean doRun)

if the element at a specified index is a Metadata object, return the value of the metadatum given by the specified name; otherwise return null.

Parameters:

index - the index of the desired Metadata element

name - the name of the metadatum to retrieve from the Metadata object.

doRun - true if it is okay to execute a Runnable object to obtain the desired metadatum when appropriate.

firstElement

public final java.lang.Object firstElement()

Returns the first element of the sequence.

lastElement

public final java.lang.Object lastElement()

Returns the last element of the sequence.

setElementAt

public final void setElementAt(java.lang.Object obj,
                               int index)

Sets the element at the specified index to be the specified object, growing the array as necessary.

Parameters:

obj - what the element is to be set to

index - the specified index

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the index is < 0

removeElementAt

public final boolean removeElementAt(int index)

Erases and (when possible) deletes the element at the specified index. If the index is greater than or equal to the number of default values, the elements with an index greater than the current index are moved down; otherwise, the element value is erased, returning it to its default value.

Parameters:

index - the element to remove

Returns:

boolean true, if removal was possible; false, if default value exists or index is out of range.

eraseElementAt

public final void eraseElementAt(int index)

erases the current value of an element, returning it to its default value. If the default value was not set at construction, the default is null

insertElementAt

public final boolean insertElementAt(java.lang.Object obj,
                                     int index)

Conditionally inserts the specified object as an element at the specified index. If the specified index greater than or equal to the number of default values, the elements with an index greater or equal to the current index are shifted up; otherwise, the insertion is not done and false is returned.

Parameters:

obj - the element to insert

index - where to insert the new element

Returns:

boolean true if request insertion was allowed and successful

addElement

public final void addElement(java.lang.Object obj)

Adds the specified object as the last element of the vector.

Parameters:

obj - the element to be added

removeElement

public final boolean removeElement(java.lang.Object obj)

Erases and (when possible) deletes the element from the vector. If the object occurs more than once, only the first is removed. If the object is not an element or not deletable, returns false.

Parameters:

obj - the element to be removed

Returns:

true if the element was actually removed; false otherwise.

removeAllElements

public final void removeAllElements()

Revert the metavector to its fully default state.

detach

public final void detach()

replace the internal default Metavector with a copy, detaching control of the defaults from the originator of this Metavector. Users should call this method to prevent the originator from updating the defaults later.

setDefaults

public void setDefaults(Metavector to)

Set the default Metavector of this Metavector object. The specified defaults replace the one previously in use. This effectively "detaches" this Metavector from its originator and "attaches" it to the caller of this method. If no other object holds a reference to the old defaults, it will get garbage-collected.

copyInto

public final void copyInto(java.lang.Object[] anArray)

Copies the elements of this vector into the specified array.

Parameters:

anArray - the array where elements get copied into

copyInto

public final void copyInto(Metavector that)

Copies the elements of this Metavector into another Metavector

Parameters:

that - the Metavector to copy into

copyIntoVector

public final java.util.Vector copyIntoVector()

Create a java.util.Vector object containing a shallow copy of the data in this metavector object.

clone

public java.lang.Object clone()

Clones this metavector. The elements are not cloned, and the defaults are still in control of this metavector's originator.

Overrides:

clone in class java.lang.Object

detachedClone

public Metavector detachedClone()

Like clone(), except that a copy of the defaults metavector is also made. This provides a fully metavector object that is fully detached from the originator of this metavector; that is, the originator can not change the defaults of the new metavector. The elements within both the primary and default arrays are not cloned.

cloneDefaults

public Metavector cloneDefaults()

clone the defaults metavector. The resulting metavector will not have a defaults list of its own and, therefore, will be detached from the control of other objects. The elements within both the primary and default arrays are not cloned.

deepClone

public final Metavector deepClone()

create a semi-deep clone. This method is like clone(), except that the Metadata and Metavector objects contained within are replaced with their own clones (using their respecitive deepClone() methods).

toString

public final java.lang.String toString()

Converts the vector to a string. Useful for debugging.

Overrides:

toString in class java.lang.Object