source: OAIProvider/trunk/src/main/java/eu/clarin/oai/provider/RecordList.java @ 1911

package eu.clarin.oai.provider;

import java.util.Date;
import java.util.List;

import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;

/**
 * A list of items from the repository as the result of a query. Used by the
 * <em>ListRecords</em> and <em>ListIdentifiers</em> verb. This can also be a
 * partial list if the repository wants do flow-control.
 * 
 * A <code>RecordList</code> object maintains a cursor pointing to its
 * current record. Initially the cursor is positioned before the first row.
 * The next method moves the cursor to the next row, and because it returns
 * <code>false</code> when there are no more records in the
 * <code>RecordList</code> object, it can be used in a while loop to iterate through the
 * result set.
 */
public interface RecordList {

    /**
     * Get the size of the complete result list.
     * 
     * @return the size of the complete result list or <code>-1</code>, if the
     *         repository cannot calculate the total size.
     * @see #getSize()
     */
    public int getTotalSize();


    /**
     * Return <code>true</code>, if no more partial result lists are available
     * for this request. In other words, this method should return
     * <code>true</code> either if this list contains all appropriate records
     * for the request or if this result list is the last partial list for the
     * request. This is needed for flow-control.
     * 
     * @return <code>true</code> if no more results are available in subsequent
     *         requests, <code>false</code> otherwise
     */
    public boolean isListComplete();


    /**
     * Release resources as this record list instance is about to be discarded.
     */
    public void close();

    
    /**
     * Returns <code>true</code> if the list has more records. (In other words,
     * returns <code>true</code> if <code>nextRecord</code> would return an
     * element rather than throwing an exception.)
     * 
     * @return <code>true</code> if the list has more records
     */
    public boolean next();

    
    /**
     * Get the localId of the record. The returned object must be compatible
     * with repository's implementation of <code>parseLocalId</code> and
     * <code>unparseLocalId</code>.
     *
     * @returns the local Id object of the record
     */
    public Object getLocalId();

    /**
     * Get the last changed timestamp of the item.
     *
     * @return the last changed timestamp of the item
     */
    public Date getDatestamp();

    /**
     * set deletion state of the record.
     *
     * @return <code>true</code> of the record is deleted, <code>false</code>
     *         otherwise
     * @see Repository#getDeletedNotion()            
     */
    public boolean isDeleted();

    /**
     * Get the sets to which this record belongs to.
     *
     * @return the list of sets to which the records belongs to or
     *         <code>null</code> if it does not belong to any sets or the
     *         repository does not support set
     */
    public List<String> getSetSpecs();

    
    public void writeRecord(XMLStreamWriter writer) throws XMLStreamException;
    
    // /**
    // * Gets the next record in the list. RecordList implementations must set
    // * the appropriate values to the passed Record instance.
    // *
    // * @param record
    // * a Record instance to gather the record data
    // * @see Record
    // * @throws NoSuchElementException - iteration has no more results.
    // */
    // public void nextRecord(Record record);
    //
    // /**
    // * Return <code>true</code>, if no more partial result lists are
    // * available for this request. In other words, this method should return
    // * <code>true</code> either if this list contains all appropriate records
    // * for the request or if this result list is the last partial list for the
    // * request. This is needed for flow-control.
    // *
    // * @return <code>true</code> if no more results are available in
    // * subsequent requests, <code>false</code> otherwise
    // */
    // public boolean isListComplete();
    //

} // class RecordList