Package org.apache.vinci.transport

Class Frame

java.lang.Object
org.apache.vinci.transport.FrameComponent
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 Details

    • Frame

      protected Frame()

  • Method Details

    • 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(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:
      UnsupportedOperationException - not implemented

    • 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:
      UnsupportedOperationException - not implemented

    • 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:
      UnsupportedOperationException - not implemented

    • fromStream

      public KeyValuePair fromStream(InputStream is) throws IOException, 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:
      IOException - Can come from the underlying input stream.
      UnsupportedOperationException - if this document model does not support key addition.
      EOFException

    • toStream

      public void toStream(OutputStream os) throws 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:
      IOException - Can come from the underlying output stream.
      UnsupportedOperationException - if this document model does not support key iteration.

    • toString

      public String toString()
      Represent the document as a string (equivlent to toXML()).
      Overrides:
      toString in class Object
      Returns:
      The document in String format.
      Throws:
      UnsupportedOperationException - if this document model does not support key iteration.

    • toXML

      public 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:
      UnsupportedOperationException - if this document model does not support key iteration.

    • toRawXML

      public String toRawXML()
      Convert the document to XML without any pretting printing.
      Returns:
      The document in XML format as a string.
      Throws:
      UnsupportedOperationException - if this document model does not support key iteration.
      Since:
      2.1.2

    • toRawXML

      public StringBuffer toRawXML(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:
      UnsupportedOperationException - if this document model does not support key iteration.
      Since:
      2.1.2

    • toRawXMLWork

      public void toRawXMLWork(StringBuffer rval)

    • toXML

      public StringBuffer toXML(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:
      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.
      Parameters:
      array - -
      Returns:
      the created FrameLeaf.

    • createSubFrame

      public Frame createSubFrame(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.
      Parameters:
      tag_name - -
      initialCapacity - -
      Returns:
      the created sub-frame.
      Throws:
      UnsupportedOperationException - if the getClass().newInstance() call on this object results in an exception.

    • toXML

      protected void toXML(StringBuffer rval, int offset)
      Helper method for toXML(StringBuffer).
      Parameters:
      rval - -
      offset - -

    • fadd

      public Frame fadd(String key, float val)
      Decorator method for adding float-valued tags.
      Parameters:
      key - The key to be associated with the value.
      val - -
      Returns:
      This frame
      Throws:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(String key, float[] val)
      Decorator method for adding float-array valued tags.
      Parameters:
      key - The key to be associated with the value.
      val - -
      Returns:
      This frame
      Throws:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(String key, double val)
      Decorator method for adding double valued tags.
      Parameters:
      key - The key to be associated with the value.
      val - -
      Returns:
      This frame
      Throws:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(String key, 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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(String key, 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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(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:
      UnsupportedOperationException - if this document model doesn't support key addition.

    • fadd

      public Frame fadd(String key)
      Decorator method for adding a valueless tag.
      Parameters:
      key - The key name.
      Returns:
      This frame.
      Throws:
      UnsupportedOperationException - if this document model doesn't support key addition, or creation of empty sub-frames.

    • faddTrueBinary

      public Frame faddTrueBinary(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:
      UnsupportedOperationException - if this document model doesn't support key addition.