java/pig-galago/src/com/yahoo/pig/StorageFunc.java

   1 /*
   2  * Copyright (c) 2007 Yahoo! Inc.  All rights reserved.
   3  * See accompanying LICENSE file.
   4  */
   5 package com.yahoo.pig;
   6
   7 import java.io.IOException;
   8 import java.io.InputStream;
   9 import java.io.OutputStream;
  10
  11 import com.yahoo.pig.data.Tuple;
  12
  13 /**
  14  * This class is used to implement functions to parse records
  15  * from a dataset.
  16  *
  17  * @author database-systems@research.yahoo
  18  *
  19  */
  20
  21 public abstract class StorageFunc extends InstantiatedFunc {
  22         /**
  23          * Specifies a portion of an FSInputStream to read tuples. Because the
  24          * starting and ending offsets may not be on record boundaries it is up to
  25          * the implementor to deal with figuring out the actual starting and ending
  26          * offsets in such a way that an arbitrarily sliced up file will be processed
  27          * in its entirety.
  28          * <p>
  29          * A common way of handling slices in the middle of records is to start at
  30          * the given offset and, if the offset is not zero, skip to the end of the
  31          * first record (which may be a partial record) before reading tuples.
  32          * Reading continues until a tuple has been read that ends at an offset past
  33          * the ending offset.
  34          *
  35          * @param is the stream representing the file to be processed.
  36          * @param offset the offset to start reading tuples.
  37          * @param end the ending offset for reading.
  38          * @throws IOException
  39          */
  40         public abstract void bindTo(InputStream is, long offset, long end) throws IOException;
  41         /**
  42          * Retrieves the next tuple to be processed.
  43          * @return the next tuple to be processed or null if there are no more tuples
  44          * to be processed.
  45          * @throws IOException
  46          */
  47         public abstract Tuple getNext() throws IOException;
  48
  49         /**
  50          * Specifies the OutputStream to write to. This will be called before
  51          * store(Tuple) is invoked.
  52          *
  53          * @param os The stream to write tuples to.
  54          * @throws IOException
  55          */
  56     public abstract void bindTo(OutputStream os) throws IOException;
  57
  58     /**
  59      * Write a tuple the output stream to which this instance was
  60      * previously bound.
  61      *
  62      * @param f the tuple to store.
  63      * @throws IOException
  64      */
  65     public abstract void putNext(Tuple f) throws IOException;
  66
  67     /**
  68      * Do any kind of post processing because the last tuple has been
  69      * stored. DO NOT CLOSE THE STREAM in this method. The stream will be
  70      * closed later outside of this function.
  71      *
  72      * @throws IOException
  73      */
  74     public abstract void done() throws IOException;
  75
  76         public String toString() {
  77         StringBuffer sb = new StringBuffer();
  78         sb.append(getName());
  79         return sb.toString();
  80     }
  81 }