org.apache.vinci.transport

Class VinciFrame

java.lang.Object

org.apache.vinci.transport.FrameComponent

org.apache.vinci.transport.Frame

org.apache.vinci.transport.QueryableFrame

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

Constructors

Constructor and Description
VinciFrame() Create a new empty VinciFrame.
VinciFrame(int initialCapacity) Create a new empty VinciFrame with the specified initial capacity.

Method Summary

Modifier and Type	Method and Description
void	add(String key, FrameComponent val) Implementation of the abstract Frame method.
Frame	createSubFrame(String tag_name, int initialCapacity) Override the createSubFrame to create a VinciFrame of precise capacity.
protected void	ensureCapacity()
VinciFrame	fdrop(String key) Remove all elements whose tag name matches the provided key (if any) from the top level of this frame.
VinciFrame	fdropFirst(String key) Remove only the first element whose tag name matches the specified key (if any) from the top level of this frame.
ArrayList	fget(String key) Implementation of the abstract fget method defined in QueryableFrame.
FrameComponent	fgetFirst(String key) Implementation of the abstract fgetFirst method defined in QueryableFrame.
VinciFrame	fgetVinciFrame(String key) Convenience method for fetching sub-frames when their type is known to be VinciFrame
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(String key, boolean val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, byte[] bin) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, double val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, Frame val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, int val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, int[] val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, long val) Change the value associated with the first occurence of the given key to val.
VinciFrame	fset(String key, String val) Change the value associated with first occurence of the given key to val.
VinciFrame	fsetTrueBinary(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(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.

Returns:

-

toVinciFrame

public static VinciFrame toVinciFrame(Transportable t)

Create a VinciFrame that is a (deep) copy of the given transportable.

Parameters:

t - -

Returns:

-

fkeys

public 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 ArrayList fget(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(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(String tag_name,
                            int initialCapacity)

Override the createSubFrame to create a VinciFrame of precise capacity.

Overrides:

createSubFrame in class Frame

Parameters:

tag_name - -

initialCapacity - -

Returns:

the created sub-frame.

fgetVinciFrame

public VinciFrame fgetVinciFrame(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:

ClassCastException - (unchecked) if the value was not of type VinciFrame.

fset

public VinciFrame fset(String key,
                       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.

Parameters:

key - -

val - -

Returns:

-

Throws:

NullPointerException - if val is null.

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

Throws:

NullPointerException - if val is null.

fset

public VinciFrame fset(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.

Parameters:

key - -

val - -

Returns:

-

fset

public VinciFrame fset(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.

Parameters:

key - -

bin - -

Returns:

-

Throws:

NullPointerException - if bin is null.

fsetTrueBinary

public VinciFrame fsetTrueBinary(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.

Parameters:

key - -

bin - -

Returns:

-

Throws:

NullPointerException - if bin is null.

set

protected void set(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.

Parameters:

key - -

val - -

Throws:

NullPointerException - if val is null.

fdropFirst

public VinciFrame fdropFirst(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(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(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.

Returns:

true if there was whitespace to strip.

Since:

2.1.2a