Package org.apache.vinci.transport

Class QueryableFrame

java.lang.Object
org.apache.vinci.transport.FrameComponent
org.apache.vinci.transport.Frame
org.apache.vinci.transport.QueryableFrame
All Implemented Interfaces:
Transportable
Direct Known Subclasses:
VinciFrame
public abstract class QueryableFrame extends Frame
QueryableFrame is a decorator class that extends Frame. While the Frame decorates its descendents with adder methods for building an XML document, the QueryableFrame further decorates its descendents with getter methods that provide simple "declarative" querying of document values. This supports the important Vinci convention of declarative value access to support evolving service schemas. Descendents of QueryableFrame need only implement the abstract fget(String key) and fgetFirst(String key) methods. Typically you will use VinciFrame, an immediate and concrete descendent of QueryableFrame, for most of your code. QueryableFrame can be extended to simplify implementation of alternate Frame implementations should VinciFrame be inadequate for whatever reason. Note that the getters of QueryableFrame do not search the document recursively. That is, they only search the "top level" tags within the Frame. More sophisticated document search methods should probably be added in orthogonal query processing classes, such as through an XPathProcessor class that understands the QueryableFrame interface.

  • Constructor Details

    • QueryableFrame

      public QueryableFrame()

  • Method Details

    • fget

      public abstract ArrayList fget(String key)
      This method must be implemented so that it returns ALL values paired with the specified key in ArrayList format. Note that this method searches only the "top level" keys, that is, keys nested within a sub-frame are not searched by this method.
      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 abstract FrameComponent fgetFirst(String key)
      This method must be implemented so that it returns only the FIRST value paired with the specified key. Note that this method searches only the "top level" keys, that is, keys nested within a sub-frame are not searched by this method.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The first value associated with the given key, or null if none exist.

    • fgetBytes

      public byte[] fgetBytes(String key)
      Presuming the data identified by this key is Base64 data, returns the binary array result of Base64 decoding that data. If there is more than one of the specified key, then the first is used. Returns null if no matching key found.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested data is not B64.
      ClassCastException - thrown if the specified frame component is not a leaf.

    • fgetTrueBinary

      public byte[] fgetTrueBinary(String key)
      This is a "non-XTalk-1.0" hack to allow retrieving any data that was transported as "true binary" (non Base64 encoded), for example via Frame.faddTrueBinary(String, byte[]) instead of Frame.fadd(String, byte[]). If there is more than one of the specified key, then the first is used. Returns null if no matching key found. You can also use this method if you simply want to get at leaf data in raw UTF-8 form.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      ClassCastException - thrown if the specified frame component is not a leaf.

    • fgetBoolean

      public boolean fgetBoolean(String key)
      Retrieve the value of the specified key as a boolean. Returns true if and only if the value of the key exactly equals the string "true" (TransportConstants.TRUE_VALUE). If there is more than one of the specified key, then the first is used.
      Parameters:
      key - The key identifying the value to be retrieved.
      Returns:
      true if the requested key exists and its value is "true", false otherwise.
      Throws:
      ClassCastException - if the specified value is not a leaf.

    • fgetFloat

      public float fgetFloat(String key) throws LeafCastException
      Retrieve the value of the specified key as a float. Throws an exception if the value could not be converted to float. Returns Float.MIN_VALUE if the key does not exist. If there is more than one of the specified key, then the first is used.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or Float.MIN_VALUE if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested value could not be converted to a float.
      ClassCastException - if the specified value is not a leaf.

    • fgetFloatArray

      public float[] fgetFloatArray(String key)
      Retrieve the value of the specified key as an array of floats. Assumes the key's value is a space separated list of tokens. If there is more than one of the specified key, then the first is used. Returns null if no matching key is found.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if *any* of the space-separated tokens cannot be converted to float.
      ClassCastException - if the specified value is not a leaf.

    • fgetDouble

      public double fgetDouble(String key)
      Retrieve the value of the specified key as a double. Throws an exception if the value could not be converted to double. Returns Double.MIN_VALUE if the key does not exist. If there is more than one of the specified key, then the first is used.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or Double.MIN_VALUE if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested value could not be converted to a double.
      ClassCastException - if the specified value is not a leaf.

    • fgetDoubleArray

      public double[] fgetDoubleArray(String key)
      Retrieve the value of the specified key as an array of doubles. Assumes the key's value is a space separated list of tokens. If there is more than one of the specified key, then the first is used. Returns null if there is no matching key.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if *any* of the space-separated tokens cannot be converted to double.
      ClassCastException - if the specified value is not a leaf.

    • fgetInt

      public int fgetInt(String key)
      Retrieve the value of the specified key as a int. Throws an exception if the value could not be converted to int. Returns Int.MIN_VALUE if the key does not exist. If there is more than one of the specified key, then the first is used.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or Int.MIN_VALUE if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested value could not be converted to a int.
      ClassCastException - if the specified value is not a leaf.

    • fgetIntArray

      public int[] fgetIntArray(String key)
      Retrieve the value of the specified key as an array of ints. Assumes the key's value is a space separated list of tokens. If there is more than one of the specified key, then the first is used. Returns null if there is no matching key.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if *any* of the space-separated tokens cannot be converted to int.
      ClassCastException - if the specified value is not a leaf.

    • fgetLong

      public long fgetLong(String key)
      Retrieve the value of the specified key as a long. Throws an exception if the value could not be converted to long. Returns Long.MIN_VALUE if the key does not exist. If there is more than one of the specified key, then the first is used.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or Long.MIN_VALUE if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested value could not be converted to a long.
      ClassCastException - if the specified value is not a leaf.

    • fgetLongArray

      public long[] fgetLongArray(String key)
      Retrieve the value of the specified key as an array of longs. Assumes the key's value is a space separated list of tokens. If there is more than one of the specified key, then the first is used. Returns null if there is no matching key.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if *any* of the space-separated tokens cannot be converted to long.
      ClassCastException - if the specified value is not a leaf.

    • fgetString

      public String fgetString(String key)
      Retrieve the value of the specified key as a String. If there is more than one of the specified key, then the first is used. Returns null if there is no matching key. If the requested value is not a leaf, then the XML of the sub-frame value is returned.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.

    • fgetStringArray

      public String[] fgetStringArray(String key)
      Retrieve the value of the specified key as a String array. If there is more than one of the specified key, then the first is used. and assumes it's a String. Use at your own risk.
      Parameters:
      key - The key identifying the value to retrieve.
      Returns:
      The requested value, or null if the specified key does not exist.
      Throws:
      LeafCastException - (unchecked) thrown if the requested value is not a properly encoded string array.
      ClassCastException - if the specified value is not a leaf.

    • fgetFrame

      public QueryableFrame fgetFrame(String key)
      Retrieve the value of the specified key as a QueryableFrame. If there is more than one of the specified key, then the first is used.
      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 QueryableFrame.