org.apache.avro.io
Class ResolvingDecoder

java.lang.Object
  extended by org.apache.avro.io.Decoder
      extended by org.apache.avro.io.ParsingDecoder
          extended by org.apache.avro.io.ValidatingDecoder
              extended by org.apache.avro.io.ResolvingDecoder
All Implemented Interfaces:
Parser.ActionHandler, SkipParser.SkipHandler

public class ResolvingDecoder
extends ValidatingDecoder

Decoder that performs type-resolution between the reader's and writer's schemas.

When resolving schemas, this class will return the values of fields in _writer's_ order, not the reader's order. (However, it returns _only_ the reader's fields, not any extra fields the writer may have written.) To help clients handle fields that appear to be coming out of order, this class defines the method readFieldOrder().

See the parser documentation for information on how this works.


Field Summary
 
Fields inherited from class org.apache.avro.io.ValidatingDecoder
in
 
Fields inherited from class org.apache.avro.io.ParsingDecoder
parser
 
Constructor Summary
ResolvingDecoder(Object resolver, Decoder in)
          Constructs a ResolvingDecoder using the given resolver.
ResolvingDecoder(Schema writer, Schema reader, Decoder in)
           
 
Method Summary
 Symbol doAction(Symbol input, Symbol top)
          Handle the action symbol top when the input is sought to be taken off the stack.
 void drain()
          Consume any more data that has been written by the writer but not needed by the reader so that the the underlying decoder is in proper shape for the next record.
 double readDouble()
          Reads a double written by Encoder.writeDouble(double).
 int readEnum()
          Reads an enumeration.
 Schema.Field[] readFieldOrder()
          Returns the actual order in which the reader's fields will be returned to the reader.
 int readIndex()
          Reads the tag of a union written by Encoder.writeIndex(int).
 long readLong()
          Reads a long written by Encoder.writeLong(long).
static Object resolve(Schema writer, Schema reader)
          Produces an opaque resolver that can be used to construct a new ResolvingDecoder(Object, Decoder).
 void skipAction()
          Skips the action at the top of the stack.
 
Methods inherited from class org.apache.avro.io.ValidatingDecoder
arrayNext, init, init, mapNext, readArrayStart, readBoolean, readBytes, readFixed, readFloat, readInt, readMapStart, readNull, readString, skipArray, skipBytes, skipFixed, skipFixed, skipMap, skipString
 
Methods inherited from class org.apache.avro.io.ParsingDecoder
skipTopSymbol
 
Methods inherited from class org.apache.avro.io.Decoder
readFixed
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ResolvingDecoder

public ResolvingDecoder(Schema writer,
                        Schema reader,
                        Decoder in)
                 throws IOException
Throws:
IOException

ResolvingDecoder

public ResolvingDecoder(Object resolver,
                        Decoder in)
                 throws IOException
Constructs a ResolvingDecoder using the given resolver. The resolver must have been returned by a previous call to resolve(Schema, Schema).

Parameters:
resolver - The resolver to use.
in - The underlying decoder.
Throws:
IOException
Method Detail

resolve

public static Object resolve(Schema writer,
                             Schema reader)
                      throws IOException
Produces an opaque resolver that can be used to construct a new ResolvingDecoder(Object, Decoder). The returned Object is immutable and hence can be simultaneously used in many ResolvingDecoders. This method is reasonably expensive, the users are encouraged to cache the result.

Parameters:
writer - The writer's schema.
reader - The reader's schema.
Returns:
The opaque reolver.
Throws:
IOException

readFieldOrder

public final Schema.Field[] readFieldOrder()
                                    throws IOException
Returns the actual order in which the reader's fields will be returned to the reader. This method is useful because ResolvingDecoder returns values in the order written by the writer, rather than the order expected by the reader. This method allows readers to figure out what fields to expect. Let's say the reader is expecting a three-field record, the first field is a long, the second a string, and the third an array. In this case, a typical usage might be as follows:
   Schema.Fields[] fieldOrder = in.readFieldOrder();
   for (int i = 0; i < 3; i++) {
     switch (fieldOrder[i].pos()) {
     case 1:
       foo(in.readLong());
       break;
     case 2:
       someVariable = in.readString();
       break;
     case 3:
       bar(in); // The code of "bar" will read an array-of-int
       break;
     }
 
Note that ResolvingDecoder will return only the fields expected by the reader, not other fields that may have been written by the writer. Thus, the iteration-count of "3" in the above loop will always be correct. Throws a runtime exception if we're not just about to read the field of a record. Also, this method will consume the field information, and thus may only be called once before reading the field value. (However, if the client knows the order of incoming fields, then the client does not need to call this method but rather can just start reading the field values.)

Throws:
AvroTypeException - If we're not starting a new record
IOException

drain

public final void drain()
                 throws IOException
Consume any more data that has been written by the writer but not needed by the reader so that the the underlying decoder is in proper shape for the next record. This situation happens when, for example, the writer writes a record with two fields and the reader needs only the first field. This function should be called after completely decoding an object but before next object can be decoded from the same underlying decoder either directly or through another resolving decoder. If the same resolving decoder is used for the next object as well, calling this method is optional; the state of this resolving decoder ensures that any leftover portions are consumed before the next object is decoded.

Throws:
IOException

readLong

public long readLong()
              throws IOException
Description copied from class: Decoder
Reads a long written by Encoder.writeLong(long).

Overrides:
readLong in class ValidatingDecoder
Throws:
IOException

readDouble

public double readDouble()
                  throws IOException
Description copied from class: Decoder
Reads a double written by Encoder.writeDouble(double).

Overrides:
readDouble in class ValidatingDecoder
Throws:
IOException

readEnum

public int readEnum()
             throws IOException
Description copied from class: Decoder
Reads an enumeration.

Overrides:
readEnum in class ValidatingDecoder
Returns:
The enumeration's value.
Throws:
IOException

readIndex

public int readIndex()
              throws IOException
Description copied from class: Decoder
Reads the tag of a union written by Encoder.writeIndex(int).

Overrides:
readIndex in class ValidatingDecoder
Throws:
IOException

doAction

public Symbol doAction(Symbol input,
                       Symbol top)
                throws IOException
Description copied from interface: Parser.ActionHandler
Handle the action symbol top when the input is sought to be taken off the stack.

Specified by:
doAction in interface Parser.ActionHandler
Overrides:
doAction in class ValidatingDecoder
Parameters:
input - The input symbol from the caller of advance
top - The symbol at the top the stack.
Returns:
null if advance() is to continue processing the stack. If not null the return value will be returned by advance().
Throws:
IOException

skipAction

public void skipAction()
                throws IOException
Description copied from interface: SkipParser.SkipHandler
Skips the action at the top of the stack.

Specified by:
skipAction in interface SkipParser.SkipHandler
Overrides:
skipAction in class ParsingDecoder
Throws:
IOException


Copyright © 2010 The Apache Software Foundation