org.apache.vinci.transport
Class VinciFrame

java.lang.Object
  extended by org.apache.vinci.transport.FrameComponent
      extended by org.apache.vinci.transport.Frame
          extended by org.apache.vinci.transport.QueryableFrame
              extended by org.apache.vinci.transport.VinciFrame
All Implemented Interfaces:
Transportable
Direct Known Subclasses:
AFrame, Attributes, ErrorFrame

public class VinciFrame
extends QueryableFrame

This is the "default" document class for use with the Vinci client and servable classes. VinciFrame implements a queryable frame from (nested) ArrayList data structures. Search time for a named tag is O(n) in the number of keys at a given depth, which is fine for all but the largest documents. VinciFrame complements the QueryableFrame adders and getters with several setter methods [fset(String, *)] for modifying the values of designated tags.


Constructor Summary
VinciFrame()
          Create a new empty VinciFrame.
VinciFrame(int initialCapacity)
          Create a new empty VinciFrame with the specified initial capacity.
 
Method Summary
 void add(java.lang.String key, FrameComponent val)
          Implementation of the abstract Frame method.
 Frame createSubFrame(java.lang.String tag_name, int initialCapacity)
          Override the createSubFrame to create a VinciFrame of precise capacity.
protected  void ensureCapacity()
           
 VinciFrame fdrop(java.lang.String key)
          Remove all elements whose tag name matches the provided key (if any) from the top level of this frame.
 VinciFrame fdropFirst(java.lang.String key)
          Remove only the first element whose tag name matches the specified key (if any) from the top level of this frame.
 java.util.ArrayList fget(java.lang.String key)
          Implementation of the abstract fget method defined in QueryableFrame.
 FrameComponent fgetFirst(java.lang.String key)
          Implementation of the abstract fgetFirst method defined in QueryableFrame.
 VinciFrame fgetVinciFrame(java.lang.String key)
          Convenience method for fetching sub-frames when their type is known to be VinciFrame
 java.util.ArrayList fkeys()
          Returns a ArrayList of all the keys at the top-level of this frame, removing any duplicates.
 void freset()
          Reset this frame to an empty state.
 VinciFrame fset(java.lang.String key, boolean val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, byte[] bin)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, double val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, Frame val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, int val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, int[] val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, long val)
          Change the value associated with the first occurence of the given key to val.
 VinciFrame fset(java.lang.String key, java.lang.String val)
          Change the value associated with first occurence of the given key to val.
 VinciFrame fsetTrueBinary(java.lang.String key, byte[] bin)
          Change the value associated with the first occurence of the given key to val.
 KeyValuePair getKeyValuePair(int which)
          Implementation of the abstract Frame method.
 int getKeyValuePairCount()
          Implementation of the abstract Frame method.
static TransportableFactory getVinciFrameFactory()
          Get a TransportableFactory that creates new VinciFrames.
protected  void set(java.lang.String key, FrameComponent val)
          Change the value associated with the first occurence of the given key to val.
 boolean stripWhitespace()
          Recursively strip any raw PCDATA fields that are entirely whitespace.
static VinciFrame toVinciFrame(Transportable t)
          Create a VinciFrame that is a (deep) copy of the given transportable.
 
Methods inherited from class org.apache.vinci.transport.QueryableFrame
fgetBoolean, fgetBytes, fgetDouble, fgetDoubleArray, fgetFloat, fgetFloatArray, fgetFrame, fgetInt, fgetIntArray, fgetLong, fgetLongArray, fgetString, fgetStringArray, fgetTrueBinary
 
Methods inherited from class org.apache.vinci.transport.Frame
createFrameLeaf, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, fadd, faddTrueBinary, fromStream, getFrameTransporter, setFrameTransporter, toRawXML, toRawXML, toRawXMLWork, toStream, toString, toXML, toXML, toXML
 
Methods inherited from class org.apache.vinci.transport.FrameComponent
getAttributes, setAttributes
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

VinciFrame

public VinciFrame()
Create a new empty VinciFrame.


VinciFrame

public VinciFrame(int initialCapacity)
Create a new empty VinciFrame with the specified initial capacity.

Parameters:
initialCapacity - the capacity value to be passed on to the internal ArrayList used for holding KeyValuePairs.
Method Detail

getVinciFrameFactory

public static TransportableFactory getVinciFrameFactory()
Get a TransportableFactory that creates new VinciFrames.


toVinciFrame

public static VinciFrame toVinciFrame(Transportable t)
Create a VinciFrame that is a (deep) copy of the given transportable.


fkeys

public java.util.ArrayList fkeys()
Returns a ArrayList of all the keys at the top-level of this frame, removing any duplicates.

Returns:
A ArrayList of keys.

fget

public java.util.ArrayList fget(java.lang.String key)
Implementation of the abstract fget method defined in QueryableFrame.

Specified by:
fget in class QueryableFrame
Parameters:
key - The key identifying the values to retrieve.
Returns:
The list of values that are paired with given key. If no such values exist, then an empty list is returned (null is never returned).

fgetFirst

public FrameComponent fgetFirst(java.lang.String key)
Implementation of the abstract fgetFirst method defined in QueryableFrame.

Specified by:
fgetFirst in class QueryableFrame
Parameters:
key - The key identifying the value to retrieve.
Returns:
The first value associated with the given key, or null if none exist.

createSubFrame

public Frame createSubFrame(java.lang.String tag_name,
                            int initialCapacity)
Override the createSubFrame to create a VinciFrame of precise capacity.

Overrides:
createSubFrame in class Frame
Returns:
the created sub-frame.

fgetVinciFrame

public VinciFrame fgetVinciFrame(java.lang.String key)
Convenience method for fetching sub-frames when their type is known to be VinciFrame

Parameters:
key - The key identifying the value to retrieve.
Returns:
The requested value, or null if the specified key does not exist.
Throws:
java.lang.ClassCastException - (unchecked) if the value was not of type VinciFrame.

fset

public VinciFrame fset(java.lang.String key,
                       java.lang.String val)
Change the value associated with first occurence of the given key to val. If the key doesn't exist, then the value is added.

Throws:
java.lang.NullPointerException - if val is null.

fset

public VinciFrame fset(java.lang.String key,
                       long val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.


fset

public VinciFrame fset(java.lang.String key,
                       boolean val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.


fset

public VinciFrame fset(java.lang.String key,
                       int val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.


fset

public VinciFrame fset(java.lang.String key,
                       int[] val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.


fset

public VinciFrame fset(java.lang.String key,
                       Frame val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.

Throws:
java.lang.NullPointerException - if val is null.

fset

public VinciFrame fset(java.lang.String key,
                       double val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.


fset

public VinciFrame fset(java.lang.String key,
                       byte[] bin)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added.

Throws:
java.lang.NullPointerException - if bin is null.

fsetTrueBinary

public VinciFrame fsetTrueBinary(java.lang.String key,
                                 byte[] bin)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added. The warnings associated with faddTrueBinary also apply to this method.

Throws:
java.lang.NullPointerException - if bin is null.

set

protected void set(java.lang.String key,
                   FrameComponent val)
Change the value associated with the first occurence of the given key to val. If the key doesn't exist, then the value is added. Note that there is no suite of methods to change *all* values associated with a given key to some value.

Throws:
java.lang.NullPointerException - if val is null.

fdropFirst

public VinciFrame fdropFirst(java.lang.String key)
Remove only the first element whose tag name matches the specified key (if any) from the top level of this frame.

Parameters:
key - The tag name of the element to remove.
Returns:
this object (NOT the component dropped).

fdrop

public VinciFrame fdrop(java.lang.String key)
Remove all elements whose tag name matches the provided key (if any) from the top level of this frame.

Parameters:
key - The tag name of the elements to remove.
Returns:
this object (NOT the component dropped).

freset

public void freset()
Reset this frame to an empty state.


add

public void add(java.lang.String key,
                FrameComponent val)
Implementation of the abstract Frame method.

Overrides:
add in class Frame
Parameters:
key - The tag name with which to associate the value.
val - The (Frame | FrameLeaf) value to associate with the tag.

ensureCapacity

protected void ensureCapacity()

getKeyValuePair

public KeyValuePair getKeyValuePair(int which)
Implementation of the abstract Frame method.

Overrides:
getKeyValuePair in class Frame
Parameters:
which - The index of the KeyValuePair to retrieve.
Returns:
The requested KeyValuePair.

getKeyValuePairCount

public int getKeyValuePairCount()
Implementation of the abstract Frame method.

Overrides:
getKeyValuePairCount in class Frame
Returns:
The total number of key/value pairs in this frame.

stripWhitespace

public boolean stripWhitespace()
Recursively strip any raw PCDATA fields that are entirely whitespace.

Since:
2.1.2a


Copyright © 2010 The Apache Software Foundation. All Rights Reserved.