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:

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.


Variable Index

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

Constructor Index

 o Metavector()
Constructs a metavector with no default values.
 o Metavector(int)
Constructs a metavector with the specified storage capacity but with no default values
 o Metavector(int, int)
Constructs an empty vector with the specified storage capacity and the specified capacityIncrement but with no default values.
 o Metavector(Metavector)
Constructs a metavector with the specified defaults
 o Metavector(Metavector, int)
Constructs a metavector with the specified storage capacity.
 o Metavector(Metavector, int, int)
Constructs a metavector with specified default values, storage capacity and capacity increment.

Method Index

 o addElement(Object)
Adds the specified object as the last element of the vector.
 o capacity()
Returns the current capacity of the vector.
 o clone()
Clones this metavector.
 o cloneDefaults()
clone the defaults metavector.
 o contains(Object)
Returns true if the specified object is a value of the collection.
 o copyInto(Metavector)
Copies the elements of this Metavector into another Metavector
 o copyInto(Object[])
Copies the elements of this vector into the specified array.
 o copyIntoVector()
Create a java.util.Vector object containing a shallow copy of the data in this metavector object.
 o deepClone()
create a semi-deep clone.
 o defaultSize()
Returns the number of elements in the vector.
 o detach()
replace the internal default Metavector with a copy, detaching control of the defaults from the originator of this Metavector.
 o detachedClone()
Like clone(), except that a copy of the defaults metavector is also made.
 o elementAt(int)
Returns the element at the specified index.
 o elementAt(int, Object)
Returns the element at the specified index.
 o elements()
Returns an enumeration of the elements.
 o ensureCapacity(int)
Ensures that the vector has at least the specified capacity.
 o eraseElementAt(int)
erases the current value of an element, returning it to its default value.
 o firstElement()
Returns the first element of the sequence.
 o 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.
 o 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.
 o indexOf(Object)
Searches for the specified object, starting from the first position and returns an index to it.
 o indexOf(Object, int)
Searches for the specified object, starting at the specified position and returns an index to it.
 o insertElementAt(Object, int)
Conditionally inserts the specified object as an element at the specified index.
 o lastElement()
Returns the last element of the sequence.
 o lastIndexOf(Object)
Searches backwards for the specified object, starting from the last position and returns an index to it.
 o lastIndexOf(Object, int)
Searches backwards for the specified object, starting from the specified position and returns an index to it.
 o 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".
 o removeAllElements()
Revert the metavector to its fully default state.
 o removeElement(Object)
Erases and (when possible) deletes the element from the vector.
 o removeElementAt(int)
Erases and (when possible) deletes the element at the specified index.
 o setDefaults(Metavector)
Set the default Metavector of this Metavector object.
 o setElementAt(Object, int)
Sets the element at the specified index to be the specified object, growing the array as necessary.
 o setSize(int)
Sets the size of the vector.
 o size()
Returns the number of elements in the vector.
 o toString()
Converts the vector to a string.
 o trimToSize()
Trims the vector's capacity down to size.

Variables

 o 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.
 o elementCount
  protected int elementCount
The number of elements in the array
 o elementData
  protected Object elementData[]
The buffer where elements are stored. The capacity of the container is given by the length of this array.
 o defaults
  protected Metavector defaults
The default values
 o 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.

Constructors

 o 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.
 o 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.
 o 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
 o 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
 o 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
 o Metavector
  public Metavector()
Constructs a metavector with no default values.

Methods

 o 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.
 o 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.
 o capacity
  public final int capacity()
Returns the current capacity of the vector.
 o 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.
 o ensureCapacity
  public final synchronized void ensureCapacity(int minCapacity)
Ensures that the vector has at least the specified capacity.
Parameters:
minCapacity - the desired minimum capacity
 o 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.
 o 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.
 o contains
  public final boolean contains(Object elem)
Returns true if the specified object is a value of the collection.
Parameters:
elem - the desired element
 o 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.
 o 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.
 o 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.
 o 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.
 o elementAt
  public final Object elementAt(int index)
Returns the element at the specified index.
Parameters:
index - the index of the desired element
 o 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.
 o 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.
 o 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).)
 o 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.
 o firstElement
  public final synchronized Object firstElement()
Returns the first element of the sequence.
 o lastElement
  public final Object lastElement()
Returns the last element of the sequence.
 o 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
 o 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.
 o 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
 o 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
 o 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
 o 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.
 o removeAllElements
  public final synchronized void removeAllElements()
Revert the metavector to its fully default state.
 o 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.
 o 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.
 o 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
 o copyInto
  public final synchronized void copyInto(Metavector that)
Copies the elements of this Metavector into another Metavector
Parameters:
that - the Metavector to copy into
 o copyIntoVector
  public final synchronized Vector copyIntoVector()
Create a java.util.Vector object containing a shallow copy of the data in this metavector object.
 o 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
 o 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.
 o 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.
 o 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).
 o 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