// AID-GENERATED
// =========================================================================
// This class was generated by AID - Abstract Interface Definition          
// DO NOT MODIFY, but use the org.freehep.aid.Aid utility to regenerate it. 
// =========================================================================

// Copyright 2002-2003, Freehep.
package hep.graphics.heprep;

import java.io.IOException;
import java.util.List;
import java.util.NoSuchElementException;

/**
 * HepRepReader interface.
 *
 * @author Mark Donszelmann
 */
public interface HepRepReader {

    /**
     * Returns a property (if set in the heprep.properties file).
     *
     * @param key property name
     * @param defaultValue value if property not found
     * @throws IOException in case of a stream problem.
     */
    public String getProperty(String key, String defaultValue) throws IOException;

    /**
     * Closes the reader and its underlying stream.
     *
     * @throws IOException in case of a stream problem.
     */
    public void close() throws IOException;

    /**
     * Allows random access.
     *
     * @return true if this reader provides random access
     * @throws IOException in case of a stream problem.
     */
    public boolean hasRandomAccess() throws IOException;

    /**
     * Reads a HepRep by name (random access only).
     *
     * @param name for the heprep to be read.
     * @return heprep.
     * @throws IOException in case of a stream problem.
     * @throws UnsupportedOperationException if the reader does not support random access.
     * @throws NoSuchElementException if the heprep is not available.
     */
    public HepRep read(String name) throws IOException, UnsupportedOperationException, NoSuchElementException;

    /**
     * Returns the current entry name (random acces only).
     *
     * @return name of the current entry or null if not supported.
     */
    public String entryName();

    /**
     * Returns a list of names of available entries (random rccess only). 
     * Zip files may contain instructions to skip a number of files. These files 
     * will not be included in the entries.
     *
     * @return list of entrynames or null if not supported.
     */
    public List/*<String>*/ entryNames();

    /**
     * Allows for sequential access.
     *
     * @return true if sequential access is possible.
     * @throws IOException in case of a stream problem.
     */
    public boolean hasSequentialAccess() throws IOException;

    /**
     * Resets a sequential HepRep reader.
     *
     * @throws IOException in case of a stream problem.
     * @throws UnsupportedOperationException if the reader does not support sequential access.
     */
    public void reset() throws IOException, UnsupportedOperationException;

    /**
     * Returns the (estimated) number of HepReps in the reader.
     * Zip files may contain instructions to skip a number of files. These files 
     * will not be included in the estimate.
     *
     * @return number of HepReps, or -1 if cannot be calculated.
     */
    public int size();

    /**
     * Skips a number of HepReps in the reader.
     * Zip files may contain instructions to skip a number of files. These files 
     * will not be included in the count to be skipped.
     *
     * @param n number of HepReps to be skipped.
     * @return number of HepReps skipped.
     * @throws UnsupportedOperationException if the reader does not support sequential access.
     */
    public int skip(int n) throws UnsupportedOperationException;

    /**
     * Is there a next heprep.
     *
     * @return true if the next heprep is available.
     * @throws UnsupportedOperationException if the reader does not support sequential access.
     * @throws IOException in case of a stream problem.
     */
    public boolean hasNext() throws IOException, UnsupportedOperationException;

    /**
     * Reads the next HepRep from the Reader.
     *
     * @return heprep.
     * @throws IOException in case of a stream problem.
     * @throws UnsupportedOperationException if the reader does not support sequential access.
     * @throws NoSuchElementException if the heprep is not available, or EOF.
     */
    public HepRep next() throws IOException, UnsupportedOperationException, NoSuchElementException;
} // class or interface