com.onionnetworks.fec.io
Class FECFile

java.lang.Object
  extended by com.onionnetworks.fec.io.FECFile

public class FECFile
extends java.lang.Object

This class provides the necessary file IO routines to go along with the raw FEC codes. It is completely thread safe for multiple readers and writers, and will automatically encode and decode the packets ass necessary. If the FECFile is originally opened in "rw" mode it will revert to "r" mode once it has recieved enough data and decoded the entire file. File Encoding Example: File f = new File(args[0]); int k = 32; // source packet per block int n = 256; // number of packets to expand each block to. int packetSize = 1024; // number of bytes in each packet. FECParameters params = new FECParameters(k,n,packetSize,f.length()); FECFile fecF = new FECFile(f,"r",params); // Read the packet with blockNum=0,stripeNum=32 into the Buffer // The read() interface is much faster if you encode multiple packets // per block and encourages you to do so. We are not going to for // simplicity. Buffer b = new Buffer(packetSize); fecF.read(new Buffer[] {b}, 0, new int[] {32}); Please see tests/FECFileTest for a further example. Thread/synchronization behavior: The FECFile tries to maintain as little contention as possible, but seeing as it involves both IO intensive and processor intensive functions, this is rather difficult.

  • Disk IO is fully synchronized. This doesn't really make any difference because you can't do two parallel IO operations on the same file anyway.
  • The highest level of synchronization is per-block reader/writer locks. This means that any number of threads may read/encode at parallel and that a write or decode operation blocks all other threads trying to access the same block. Since encoding is a CPU intensive task, there will be minimal gains from parallel encoding, but the opportunity for encoding and disk IO to occur in parallel may afford some savings. (c) Copyright 2001 Onion Networks (c) Copyright 2000 OpenCola

    Author:
    Justin F. Chapweske (justin@chapweske.com)

    Nested Class Summary
     class FECFile.Decoder
               
     
    Constructor Summary
    FECFile(java.io.File f, java.lang.String mode, FECParameters params)
              Open the file according to mode
    FECFile(java.io.File f, java.lang.String mode, FECParameters params, com.onionnetworks.util.FileIntegrity integrity)
              Open the file according to mode
     
    Method Summary
     void acquireAllWriteLocks()
              Acquires all write block locks.
     void addFECIOListener(FECIOListener fil)
              Adds a new FECIOListener.
     void close()
              Close the underlying file descriptor and free up the resources associated with this FECFile.
     boolean containsPacket(int blockNum, int stripeNum)
               
     int getDecodedBlockCount()
               
     FECParameters getFECParameters()
               
     int getWrittenCount()
               
     boolean isBlockDecoded(int blockNum)
               
     boolean isDecoded()
               
     void read(com.onionnetworks.util.Buffer[] pkts, int blockNum, int[] stripeNums)
              This method reads a number of packets (encoding them if necessary) into the provided buffers.
     void releaseAllWriteLocks()
              Releases all write block locks.
     void removeFECIOListener(FECIOListener fil)
               
     void renameTo(java.io.File destFile)
              When the File is opened in r/w mode you must specify a destination.
     void setDecodeExceptionHandler(com.onionnetworks.util.ExceptionHandler eh)
              Sets the ExceptionHandler for dealing with problems that occur during decoding.
     void waitForFileDecoded()
              This method blocks and returns once the file has been decoded.
     int write(com.onionnetworks.util.Buffer pkt, int blockNum, int stripeNum)
              Writes a packet to disk.
     
    Methods inherited from class java.lang.Object
    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Constructor Detail

    FECFile

    public FECFile(java.io.File f,
                   java.lang.String mode,
                   FECParameters params)
            throws java.io.IOException
    Open the file according to mode
    Parameters:
    f - The File to which the data will be read/written
    mode - Either "r" or "rw"
    params - The FECParameters that specify how the data will be encoded and decoded.
    Throws:
    java.io.IOException

    FECFile

    public FECFile(java.io.File f,
                   java.lang.String mode,
                   FECParameters params,
                   com.onionnetworks.util.FileIntegrity integrity)
            throws java.io.IOException
    Open the file according to mode
    Parameters:
    f - The File to which the data will be read/written
    mode - Either "r" or "rw"
    params - The FECParameters that specify how the data will be encoded and decoded.
    integrity - Used for checking the file integrity.
    Throws:
    java.io.IOException
    Method Detail

    setDecodeExceptionHandler

    public void setDecodeExceptionHandler(com.onionnetworks.util.ExceptionHandler eh)
    Sets the ExceptionHandler for dealing with problems that occur during decoding.

    Parameters:
    ExceptionHandler - This object that will handle the exception.

    renameTo

    public void renameTo(java.io.File destFile)
                  throws java.io.IOException
    When the File is opened in r/w mode you must specify a destination. This method allows you to specify the destination lazily to allow downloads to take place before the user has even chosen the final location with their file picker. Be ware that the final write to that would cause the file to be moved and re-opened will block until the destination file is set, so make sure to set it asap.

    Throws:
    java.io.IOException

    read

    public void read(com.onionnetworks.util.Buffer[] pkts,
                     int blockNum,
                     int[] stripeNums)
              throws java.io.IOException,
                     PacketNotFoundException
    This method reads a number of packets (encoding them if necessary) into the provided buffers. The method accepts an array of stripeNums and an array of Buffers because it is vastly more efficient to encode multiple blocks all at once rather than across multiple method calls. Calls to read should be safe even during the rw->r switch because a packet that existed will never become unavailable.

    Parameters:
    pkts - The array of Buffers into which the data will be stored each Buffer must be params.getPacketSize() in length.
    blockNum - The block num of the packets to encode.
    stripeNums - The stripe nums of the packets to encode.
    Throws:
    java.io.IOException - If there is an IOException in the underlying file IO.
    PacketNotFoundException - If the desired packet can not be found in the PacketPlacement.

    write

    public int write(com.onionnetworks.util.Buffer pkt,
                     int blockNum,
                     int stripeNum)
              throws java.io.IOException,
                     FileAlreadyDecodedException
    Writes a packet to disk. If the packet is the k'th packet that has been written for this block, then the block will be decoded in this call. Since decoding is a relatively costly process it may cause your program to experience some bursty behavior in how long the write calls take. None-the-less if you are making any timing judgements based off of IO then you are an idiot. If this packet is the last packet that needs to be written to disk in order to decode the whole file, the block will be decoded and then the file will be properly truncated, closed, moved to the destination file and re-opened in read-only mode. If the destFile has not been set yet then this will block until that is set.

    Parameters:
    pkt - The Buffer from which the data will be written.
    blockNum - The blockNum of the packet to be written.
    stripeNum - The stripeNum of the packet to be written.
    Returns:
    The block packet count after writing this packet. This gives you the order the packets were written in for this block.
    Throws:
    java.io.IOException - When there is a disk IOException.
    DuplicatePacketException - When there is an attempt to write a packet a second time.
    BlockAlreadyDecodedException - When the block is already decoded.
    FileAlreadyDecodedException - When you are trying to write a packet when the file has been decoded and switched to read-only

    acquireAllWriteLocks

    public void acquireAllWriteLocks()
                              throws java.lang.InterruptedException
    Acquires all write block locks. This method ABSOLUTELY CANNOT be called if a blockLock has already been acquired by this thread because of the possibility for deadly embrace.

    Throws:
    java.lang.InterruptedException

    releaseAllWriteLocks

    public void releaseAllWriteLocks()
                              throws java.lang.InterruptedException
    Releases all write block locks. This method ABSOLUTELY CANNOT be called if a blockLock has already been acquired by this thread because of the possibility for deadly embrace.

    Throws:
    java.lang.InterruptedException

    close

    public void close()
               throws java.io.IOException
    Close the underlying file descriptor and free up the resources associated with this FECFile.

    Throws:
    java.io.IOException

    addFECIOListener

    public void addFECIOListener(FECIOListener fil)
    Adds a new FECIOListener.


    removeFECIOListener

    public void removeFECIOListener(FECIOListener fil)

    getDecodedBlockCount

    public int getDecodedBlockCount()
    Returns:
    The decoded block count

    isBlockDecoded

    public boolean isBlockDecoded(int blockNum)
    Returns:
    true if the block is decoded.

    containsPacket

    public boolean containsPacket(int blockNum,
                                  int stripeNum)
    Returns:
    true if the FECFile contains the specified packet.

    getWrittenCount

    public int getWrittenCount()
    Returns:
    The number of packets written to disk.

    getFECParameters

    public FECParameters getFECParameters()
    Returns:
    The FECParameters used for encoding/decoding.

    isDecoded

    public boolean isDecoded()
    Returns:
    true if this file is decoded.

    waitForFileDecoded

    public void waitForFileDecoded()
                            throws java.lang.InterruptedException
    This method blocks and returns once the file has been decoded. This is primarily so that you know when it is safe to close the FECFile without having to setup your own FECFileListeners to wait for the FileDecodedEvent.

    Throws:
    java.lang.InterruptedException


    Copyright © 2002 Onion Networks. All Rights Reserved.