    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