ChunkReader.java

package org.jaudiotagger.audio.asf.io;

import org.jaudiotagger.audio.asf.data.Chunk;
import org.jaudiotagger.audio.asf.data.GUID;

import java.io.IOException;
import java.io.InputStream;

/**
 * A ChunkReader provides methods for reading an ASF chunk.<br>
 * 
 * @author Christian Laireiter
 */
public interface ChunkReader {

    /**
     * Tells whether the reader can fail to return a valid chunk.<br>
     * The current Use would be a modified version of {@link StreamChunkReader},
     * which is configured to only manage audio streams. However, the primary
     * GUID for audio and video streams is the same. So if a stream shows itself
     * to be a video stream, the reader would return <code>null</code>.<br>
     * 
     * @return <code>true</code>, if further analysis of the chunk can show,
     *         that the reader is not applicable, despite the header GUID
     *         {@linkplain #getApplyingIds() identification} told it can handle
     *         the chunk.
     */
    boolean canFail();

    /**
     * Returns the GUIDs identifying the types of chunk, this reader will parse.<br>
     * 
     * @return the GUIDs identifying the types of chunk, this reader will parse.<br>
     */
    GUID[] getApplyingIds();

    /**
     * Parses the chunk.
     * 
     * @param guid
     *            the GUID of the chunks header, which is about to be read.
     * @param stream
     *            source to read chunk from.<br>
     *            No {@link GUID} is expected at the currents stream position.
     *            The length of the chunk is about to follow.
     * @param streamPosition
     *            the position in stream, the chunk starts.<br>
     * @return the read chunk. (Mostly a subclass of {@link Chunk}).<br>
     * @throws IOException
     *             On I/O Errors.
     */
    Chunk read(GUID guid, InputStream stream, long streamPosition)
            throws IOException;
}