Class ncsa.horizon.util.Metavector
All Packages Class Hierarchy This Package Previous Next Index
Class ncsa.horizon.util.Metavector
java.lang.Object
|
+----ncsa.horizon.util.Metavector
- public class Metavector
- extends Object
- implements Cloneable
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.
-
capacityIncrement
- amount to increase the capacity of the internal array when additional
data slots are needed.
-
defaults
- The default values
-
elementCount
- The number of elements in the array
-
elementData
- The buffer where elements are stored.
-
executeRunners
- true if Runnable objects should be executed to obtain values
for requested metadata when available.
-
Metavector()
- Constructs a metavector with no default values.
-
Metavector(int)
- Constructs a metavector with the specified storage capacity but
with no default values
-
Metavector(int, int)
- Constructs an empty vector with the specified storage
capacity and the specified capacityIncrement but with no default
values.
-
Metavector(Metavector)
- Constructs a metavector with the specified defaults
-
Metavector(Metavector, int)
- Constructs a metavector with the specified storage capacity.
-
Metavector(Metavector, int, int)
- Constructs a metavector with specified default values, storage
capacity and capacity increment.
-
addElement(Object)
- Adds the specified object as the last element of the vector.
-
capacity()
- Returns the current capacity of the vector.
-
clone()
- Clones this metavector.
-
cloneDefaults()
-
clone the defaults metavector.
-
contains(Object)
- Returns true if the specified object is a value of the
collection.
-
copyInto(Metavector)
- Copies the elements of this Metavector into another Metavector
-
copyInto(Object[])
- Copies the elements of this vector into the specified array.
-
copyIntoVector()
- Create a java.util.Vector object containing a shallow copy of
the data in this metavector object.
-
deepClone()
- create a semi-deep clone.
-
defaultSize()
- Returns the number of elements in the vector.
-
detach()
- replace the internal default Metavector with a copy, detaching
control of the defaults from the originator of this Metavector.
-
detachedClone()
- Like clone(), except that a copy of the defaults metavector is also
made.
-
elementAt(int)
- Returns the element at the specified index.
-
elementAt(int, Object)
- Returns the element at the specified index.
-
elements()
- Returns an enumeration of the elements.
-
ensureCapacity(int)
- Ensures that the vector has at least the specified capacity.
-
eraseElementAt(int)
-
erases the current value of an element, returning it to its default
value.
-
firstElement()
- Returns the first element of the sequence.
-
getMetadatum(int, String)
- 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.
-
getMetadatum(int, String, boolean)
- 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.
-
indexOf(Object)
- Searches for the specified object, starting from the first position
and returns an index to it.
-
indexOf(Object, int)
- Searches for the specified object, starting at the specified
position and returns an index to it.
-
insertElementAt(Object, int)
- Conditionally inserts the specified object as an element at the
specified index.
-
lastElement()
- Returns the last element of the sequence.
-
lastIndexOf(Object)
- Searches backwards for the specified object, starting from the last
position and returns an index to it.
-
lastIndexOf(Object, int)
- Searches backwards for the specified object, starting from the specified
position and returns an index to it.
-
parseOutElement(String)
- 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".
-
removeAllElements()
- Revert the metavector to its fully default state.
-
removeElement(Object)
- Erases and (when possible) deletes the element from the vector.
-
removeElementAt(int)
- Erases and (when possible) deletes the element at the specified
index.
-
setDefaults(Metavector)
- Set the default Metavector of this Metavector object.
-
setElementAt(Object, int)
- Sets the element at the specified index to be the specified object,
growing the array as necessary.
-
setSize(int)
- Sets the size of the vector.
-
size()
- Returns the number of elements in the vector.
-
toString()
- Converts the vector to a string.
-
trimToSize()
- Trims the vector's capacity down to size.
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 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.
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.
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 synchronized 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 synchronized void ensureCapacity(int minCapacity)
- Ensures that the vector has at least the specified capacity.
- Parameters:
- minCapacity - the desired minimum capacity
setSize
public final synchronized 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 synchronized 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(Object elem)
- Returns true if the specified object is a value of the
collection.
- Parameters:
- elem - the desired element
indexOf
public final int indexOf(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 synchronized int indexOf(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(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 synchronized int lastIndexOf(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 Object elementAt(int index)
- Returns the element at the specified index.
- Parameters:
- index - the index of the desired element
elementAt
public final Object elementAt(int index,
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 final static ValueAndStatus parseOutElement(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 Object getMetadatum(int index,
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 Object getMetadatum(int index,
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 synchronized Object firstElement()
- Returns the first element of the sequence.
lastElement
public final Object lastElement()
- Returns the last element of the sequence.
setElementAt
public final synchronized void setElementAt(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: ArrayIndexOutOfBoundsException
- If the index is < 0
removeElementAt
public final synchronized 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 synchronized 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 synchronized boolean insertElementAt(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 synchronized void addElement(Object obj)
- Adds the specified object as the last element of the vector.
- Parameters:
- obj - the element to be added
removeElement
public final synchronized boolean removeElement(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 synchronized void removeAllElements()
- Revert the metavector to its fully default state.
detach
public final synchronized 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 synchronized 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 synchronized void copyInto(Object anArray[])
- Copies the elements of this vector into the specified array.
- Parameters:
- anArray - the array where elements get copied into
copyInto
public final synchronized void copyInto(Metavector that)
- Copies the elements of this Metavector into another Metavector
- Parameters:
- that - the Metavector to copy into
copyIntoVector
public final synchronized Vector copyIntoVector()
- Create a java.util.Vector object containing a shallow copy of
the data in this metavector object.
clone
public synchronized 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 Object
detachedClone
public synchronized 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 synchronized 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 synchronized 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 synchronized String toString()
- Converts the vector to a string. Useful for debugging.
- Overrides:
- toString in class Object
All Packages Class Hierarchy This Package Previous Next Index