/**
 * 
 */
package at.gv.egiz.pdfas.api.io;

import java.io.InputStream;

/**
 * Input document data source.
 * 
 * <p>
 * This allows the holder of the data to decide how the data is to be stored (e.g. in a File or in a byte array).
 * </p>
 * 
 * @author wprinz
 * 
 */
public interface DataSource
{
  /**
   * Creates a new InputStream that allows to read out the document's binary
   * data from the beginning.
   * 
   * @return Returns the InputStream with the binary data.
   */
  public InputStream createInputStream();

  /**
   * Returns the length (number of bytes) of the stream.
   * 
   * @return Returns the length (number of bytes) of the stream.
   */
  public int getLength();

  /**
   * Returns the data of this DataSource as a byte array for random read only access.
   * 
   * <p>
   * Calling this method indicates that you need a byte array for random
   * <strong>read only</strong> access. The DataSource implementation should of
   * course cache this byte array to avoid too much memory usage.
   * </p>
   * <p>
   * Performance analysis has shown that the libraries internally convert the
   * streams to byte arrays and that file system access is very slow.
   * </p>
   * <p>
   * Never write to this byte array!
   * </p>
   * 
   * @return Returns the data of this DataSource as a byte array for random read only access.
   */
  public byte[] getAsByteArray();

  /**
   * Returns the mime type of the data.
   * 
   * @return Returns the mime type of the data.
   */
  public String getMimeType();

  /**
   * Returns the character encoding of the data.
   * 
   * <p>
   * This makes only sense for character based mime types.
   * </p>
   * 
   * @return Returns the character encoding of the data or null if no encoding
   *         is applicable (e.g. if the data is binary).
   */
  public String getCharacterEncoding();

}