org.apache.vinci.transport
Class Frame

java.lang.Object
  extended by org.apache.vinci.transport.FrameComponent
      extended by org.apache.vinci.transport.Frame
All Implemented Interfaces:
Transportable
Direct Known Subclasses:
QueryableFrame, ResolveResult, ResolveResult.ServiceLocator, ServeonResult

public abstract class Frame
extends FrameComponent
implements Transportable

Frame is an abstract class that is intended to be extended to implement a simple & lean (restricted) XML document model. A Frame is only capable of representing XML documents with no attributes or processing instructions. Applications which require attributes should use the org.apache.vinci.transport.document.AFrame document model instead. Frame "decorates" its descendents with several type-safe adder methods for building the XML document. It requires its descendents implement only a single generic adder method [add(String, FrameComponent)] and a getter for retreiving fields of the document by their position [getKeyValuePair(int)]. The Frame descendent QueryableFrame provides additional getter methods. QueryableFrame should be extended instead of Frame if this more powerful query support is necessary. Frame also implements the Transportable interface and provides a default marshaller for converting to and from XTalk wire format. The marshaller is pluggable to support marshalling to and from other formats if so desired, or to support optimized (e.g. native) implementation. Typically you will use VinciFrame, a concrete descendent of the (Queryable)Frame class, for most of your code. You may however also wish to implement specialized Frame descendents for optimized and/or type-safe handling of particular queries. For example, see ResolveResult and ServeonResult (in package org.apache.vinci.transport.vns.client), which do this for the two most common VNS queries. Automated stub generators may also wish to extend Frame to generate Java object to Vinci XML document adapters.


Constructor Summary
protected Frame()
           
 
Method Summary
 void add(java.lang.String tag, FrameComponent val)
          Add a tagged value to this frame (value is either a Frame or FrameLeaf).
 FrameLeaf createFrameLeaf(byte[] array)
          Factory method used by fromStream when it needs to create a frame leaf.
 Frame createSubFrame(java.lang.String tag_name, int initialCapacity)
          Factory method used by fromStream when it needs to create a sub-frame.
 Frame fadd(java.lang.String key)
          Decorator method for adding a valueless tag.
 Frame fadd(java.lang.String key, boolean val)
          Decorator method for adding boolean valued tags.
 Frame fadd(java.lang.String key, byte[] val)
          Decorator method for adding binary valued tags.
 Frame fadd(java.lang.String key, double val)
          Decorator method for adding double valued tags.
 Frame fadd(java.lang.String key, double[] val)
          Decorator method for adding double-array valued tags.
 Frame fadd(java.lang.String key, float val)
          Decorator method for adding float-valued tags.
 Frame fadd(java.lang.String key, float[] val)
          Decorator method for adding float-array valued tags.
 Frame fadd(java.lang.String key, Frame val)
          Decorator method for adding Frame-valued tags.
 Frame fadd(java.lang.String key, int val)
          Decorator method for adding int valued tags.
 Frame fadd(java.lang.String key, int[] val)
          Decorator method for adding int-array valued tags.
 Frame fadd(java.lang.String key, long val)
          Decorator method for adding long valued tags.
 Frame fadd(java.lang.String key, long[] val)
          Decorator method for adding long-array valued tags.
 Frame fadd(java.lang.String key, java.lang.String val)
          Decorator method for adding String valued tags.
 Frame fadd(java.lang.String key, java.lang.String[] val)
          Decorator method for adding String-array valued tags.
 Frame faddTrueBinary(java.lang.String key, byte[] val)
          This is a hack method which allows you to add binary-valued tags to Frames in a manner such that there is no textual encoding overhead of that binary data.
 KeyValuePair fromStream(java.io.InputStream is)
          Populate this document using the given InputStream and the installed marshaller.
static FrameTransporter getFrameTransporter()
          Get the currently installed document marshaller.
 KeyValuePair getKeyValuePair(int which)
          Return the specified KeyValue pair.
 int getKeyValuePairCount()
          Return the number of key/value pairs within this frame.
static void setFrameTransporter(FrameTransporter transporter)
          This method lets you replace the default XTalk marshaller with another one, for example if you want to use a different wire format (such as XML/SOAP), or if you want to easily exploit an optimized/native implementation.
 java.lang.String toRawXML()
          Convert the document to XML without any pretting printing.
 java.lang.StringBuffer toRawXML(java.lang.StringBuffer buf)
          Convert the document to XML without any pretting printing.
 void toRawXMLWork(java.lang.StringBuffer rval)
           
 void toStream(java.io.OutputStream os)
          Write this document to the given output stream using the installed marshaller.
 java.lang.String toString()
          Represent the document as a string (equivlent to toXML()).
 java.lang.String toXML()
          Convert the document to XML.
 java.lang.StringBuffer toXML(java.lang.StringBuffer buf)
          Append the document, in XML format, to the provided StringBuffer.
protected  void toXML(java.lang.StringBuffer rval, int offset)
          Helper method for toXML(StringBuffer).
 
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

Frame

protected Frame()
Method Detail

setFrameTransporter

public static void setFrameTransporter(FrameTransporter transporter)
This method lets you replace the default XTalk marshaller with another one, for example if you want to use a different wire format (such as XML/SOAP), or if you want to easily exploit an optimized/native implementation.

Parameters:
transporter - The new marshaller to plug in.

getFrameTransporter

public static FrameTransporter getFrameTransporter()
Get the currently installed document marshaller.

Returns:
The currently installed document marshaller.

add

public void add(java.lang.String tag,
                FrameComponent val)
Add a tagged value to this frame (value is either a Frame or FrameLeaf). Frames that support marshalling from a stream must implement this method. While the method is conceptually abstract, I provide a default error-only implementation in cases where marshalling the document to a stream is not necessary (e.g. the document is used as an input source only).

Parameters:
tag - The tag name with which to associate the value.
val - The (Frame | FrameLeaf) value to associate with the tag.
Throws:
java.lang.UnsupportedOperationException

getKeyValuePair

public KeyValuePair getKeyValuePair(int which)
Return the specified KeyValue pair. Frames that support marshalling to (but not from) a stream via the Transportable interface must implement this method. We chose this simple iteration method over providing an interator object since it doesn't require allocating any new objects. While conceptually abstract, I provide a default error-only implementation to avoid the need to define it in cases where alternative getters are provided for querying the document, and the object is never marshalled to a stream.

Parameters:
which - The index of the KeyValuePair to retrieve.
Returns:
The requested KeyValuePair.
Throws:
java.lang.UnsupportedOperationException

getKeyValuePairCount

public int getKeyValuePairCount()
Return the number of key/value pairs within this frame. Frames that support marshalling to (but not from) a stream via the Transportable interface must implement this method. While conceptually abstract, I provide a default error-only implementation to avoid the need to define it in cases where alternative getters are provided for querying the document, and the object is never marshalled to a stream.

Returns:
The total number of key/value pairs in this frame.
Throws:
java.lang.UnsupportedOperationException

fromStream

public KeyValuePair fromStream(java.io.InputStream is)
                        throws java.io.IOException,
                               java.io.EOFException
Populate this document using the given InputStream and the installed marshaller.

Specified by:
fromStream in interface Transportable
Parameters:
is - The input stream to read from.
Returns:
The first key/value pair encountered, if it comes from the Vinci namespace.
Throws:
java.io.IOException - Can come from the underlying input stream.
java.lang.UnsupportedOperationException - if this document model does not support key addition.
java.io.EOFException

toStream

public void toStream(java.io.OutputStream os)
              throws java.io.IOException
Write this document to the given output stream using the installed marshaller.

Specified by:
toStream in interface Transportable
Parameters:
os - The stream to where the document is written.
Throws:
java.io.IOException - Can come from the underlying output stream.
java.lang.UnsupportedOperationException - if this document model does not support key iteration.

toString

public java.lang.String toString()
Represent the document as a string (equivlent to toXML()).

Overrides:
toString in class java.lang.Object
Returns:
The document in String format.
Throws:
java.lang.UnsupportedOperationException - if this document model does not support key iteration.

toXML

public java.lang.String toXML()
Convert the document to XML. Performs limited pretty printing -- if you don't want any pretty printing, use toRawXML().

Returns:
The document in XML format as a string.
Throws:
java.lang.UnsupportedOperationException - if this document model does not support key iteration.

toRawXML

public java.lang.String toRawXML()
Convert the document to XML without any pretting printing.

Returns:
The document in XML format as a string.
Throws:
java.lang.UnsupportedOperationException - if this document model does not support key iteration.
Since:
2.1.2

toRawXML

public java.lang.StringBuffer toRawXML(java.lang.StringBuffer buf)
Convert the document to XML without any pretting printing.

Parameters:
buf - The StringBuffer to append the document text to.
Returns:
The StringBuffer that was provided as input
Throws:
java.lang.UnsupportedOperationException - if this document model does not support key iteration.
Since:
2.1.2

toRawXMLWork

public void toRawXMLWork(java.lang.StringBuffer rval)

toXML

public java.lang.StringBuffer toXML(java.lang.StringBuffer buf)
Append the document, in XML format, to the provided StringBuffer.

Parameters:
buf - The StringBuffer where the document is appended.
Returns:
The same StringBuffer provided to this method using the buf argument.
Throws:
java.lang.UnsupportedOperationException - if this document model does not support key iteration.

createFrameLeaf

public FrameLeaf createFrameLeaf(byte[] array)
Factory method used by fromStream when it needs to create a frame leaf. Default implementation creates a regular FrameLeaf.

Returns:
the created FrameLeaf.

createSubFrame

public Frame createSubFrame(java.lang.String tag_name,
                            int initialCapacity)
Factory method used by fromStream when it needs to create a sub-frame. Default implementation creates a subframe of the same type as the current frame.

Returns:
the created sub-frame.
Throws:
java.lang.UnsupportedOperationException - if the getClass().newInstance() call on this object results in an exception.

toXML

protected void toXML(java.lang.StringBuffer rval,
                     int offset)
Helper method for toXML(StringBuffer).


fadd

public Frame fadd(java.lang.String key,
                  float val)
Decorator method for adding float-valued tags.

Parameters:
key - The key to be associated with the value.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  float[] val)
Decorator method for adding float-array valued tags.

Parameters:
key - The key to be associated with the value.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  double val)
Decorator method for adding double valued tags.

Parameters:
key - The key to be associated with the value.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  double[] val)
Decorator method for adding double-array valued tags. Adding a null array results in a no-op.

Parameters:
key - The key to be associated with the value.
val - The array to add. The array is immediately converted to string representation.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  int val)
Decorator method for adding int valued tags.

Parameters:
key - The key to be associated with the value.
val - The int to add.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  int[] val)
Decorator method for adding int-array valued tags. Adding a null value results in a no-op.

Parameters:
key - The key to be associated with the value.
val - The array to add. The array is immediately converted to string representation.
Returns:
This frame
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  long val)
Decorator method for adding long valued tags.

Parameters:
key - The key to be associated with the value.
val - The long value to add.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  long[] val)
Decorator method for adding long-array valued tags. Adding a null value results in a no-op.

Parameters:
key - The key to be associated with the value.
val - The array to add. The array is immediately converted to string representation.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  java.lang.String val)
Decorator method for adding String valued tags.

Parameters:
key - The key to be associated with the value.
val - The string to add.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  java.lang.String[] val)
Decorator method for adding String-array valued tags. Adding a null value results in a no-op. This implementation will use the '#' char as the string separator. If the '#' char is used in some string, then the implementation generates a separator that is not contained by any string and prepends the separator to the string for extraction. The generated separator always will begin and end with the character '#'. This allows arbitrary string arrays to be sent as a single string without separator conflicts.

Parameters:
key - The key to be associated with the value.
val - The string to add.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  byte[] val)
Decorator method for adding binary valued tags. Encodes the data in Base64. Adding a null value results in a no-op.

Parameters:
key - The key to be associated with the value.
val - The binary data to add (will be Base64 encoded).
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  boolean val)
Decorator method for adding boolean valued tags.

Parameters:
key - The key to be associated with the value.
val - The boolean value to add.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key,
                  Frame val)
Decorator method for adding Frame-valued tags. Adding a null value results in a no-op.

Parameters:
key - The key to be associated with the value.
val - The sub-frame to add. Note this frame is not copied.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.

fadd

public Frame fadd(java.lang.String key)
Decorator method for adding a valueless tag.

Parameters:
key - The key name.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition, or creation of empty sub-frames.

faddTrueBinary

public Frame faddTrueBinary(java.lang.String key,
                            byte[] val)
This is a hack method which allows you to add binary-valued tags to Frames in a manner such that there is no textual encoding overhead of that binary data. This is NOT necessarily XTalk-1.0 compatible which formally requires only UTF-8, but it still works. Binary data added using this method can be retrieved using QueryableFrame/VinciFrame getter method fgetTrueBinary(String). Adding a null value results in a no-op. WARNING: if the default XTalk parser is replaced with another one, applications that depend on this method may break! WARNING #2: This method should only be used when performance hit of Base64 encoding binary data [as performed by fadd(String, byte[])] is unacceptable. WARNING #3: The byte array is NOT copied, thus it is up to the caller to ensure that the byte array cannot be modified by external code after passed in to this object.

Parameters:
key - The key to be associated with the value.
val - The byte array to be added to the frame. Note the array is NOT copied or converted in any way.
Returns:
This frame.
Throws:
java.lang.UnsupportedOperationException - if this document model doesn't support key addition.


Copyright © 2012. All Rights Reserved.