source: trunk/gsdl3/src/java/org/greenstone/gsdl3/gs3build/doctypes/DocumentInterface.java@ 5800

package org.greenstone.gsdl3.gs3build.doctypes;

import java.util.List;
import java.util.Map;

import org.greenstone.gsdl3.gs3build.metadata.*;

import org.greenstone.gsdl3.gs3build.util.MultiMap;

public interface DocumentInterface
{
    /**
     *  Get the immediate document type of the document.  The type may be derived/inherited
     *  from other DocumentInterface types, but that cannot be checked here.
     *
     *  @return <code>String</code> the document type as a string
     */
    public String getDocumentType();

    /**
     *  Check if this document is of a particular type, or is derived from a particular
     *  type - i.e. inheritance is considered as well as the immediate type.
     *
     *  @param  <code>String</code> the type to check against.
     *  @return <code>boolean</code> if the document matches the given type.
     */
    public boolean isDocumentType(String documentType);

    public void setID(DocumentID id);
    public DocumentID getID();

    /**
     *  Get the METS type of the document.
     *
     *  @return <code>String</code> the document type as a string
     */
    public String getMETSType();

    public void setHeader(METSHeader header);
    public METSHeader getHeader();

    /**
     *  Whether the document is indexed or not.
     *
     *  @return <code>boolean</code> <code>true</code> by default.
     */
    public boolean isIndexed();

    /**
     *  The plain text of the document.
     *
     *  @return <code>String</code> This value may be <code>null</code>
     *          for documents which have no textual component - e.g.
     *          an image file
     */
    public String getDocumentText();
    
    /**
     *  The metadata for the document, encoded as a map.
     *
     *  The returned Map may have the following properties:
     *  1) It may be <code>null</code> - e.g. for plain text documents
     *  2) Any value in the map may be a <code>List</code> object containing
     *     more than one possible value - e.g. they key 'Author' may associated
     *     with a List of several people.
     *  3) Any value in the map may itself be a <code>Map</code> where the
     *     encoding scheme permits groupings of hierarchical metadata items.
     *  4) Where the namespace for a metadata item is known, its key will
     *     include the namespace.  Hence Dublin Core 'Author' would be encoded
     *     as "dc.Author" as the key.
     *
     *  @return <code>METSDescriptive</code> the metadata of the document
     */
    public METSDescriptiveSet getDocumentMetadata();

    /**
     *  The metadata for the document, encoded as a map.
     *
     *  @param <code>String</code> the namespace of the metadata
     *  @param <code>String</code> the label of the values to obtain
     *
     *  @return <code>List</code> the metadata values
     */
    public List getDocumentMetadataItem(String namespace, String label);

    /**
     *  The metadata for the document, encoded as a map.
     *
     *  @param <code>String</code> the namespace and label of the metadata, separated
     *                             by a colon.  If no namespace is given, it is 
     *                             defaulted
     *
     *  @return <code>List</code> the metadata values
     */
    public List getDocumentMetadataItem(String namespaceLabel);

    /**
     *  Facilitate the decoration of a document with external or extracted
     *  metadata.  This is a "cheap" form which doesn't have a separate
     *  namespace element.  Either the data is to be stored in the "open"
     *  Greenstone metadata namespace, or the namespace is encoded within
     *  the label.
     *
     *  @param <code>String</code> label of the metadata, with a '.' to deliminate
     *                             sub-component structures.  The label may commence
     *                             with a namespace followed by a colon. 
     *                             <p>e.g. "dc:title" for Dublin Core Title.</p>
     *  @param <code>String</code> value of the metadata
     */
    public void addDocumentMetadata(String label, String value);

    /**
     *  Facilitate the decoration of a document with external or extracted
     *  metadata.
     *
     *  @param <code>String</code> namespace of the metadata
     *  @param <code>String</code> label of the metadata, with a '.' to deliminate
     *                             sub-component structures
     *  @param <code>String</code> value of the metadata
     */
    public void addDocumentMetadata(String namespace, String label, String value);

    /**
     *  The constituent files for the document: each should be wrapped up
     *  as a URL
     *
     *  @return <code>METSFileSet</code> the files which constitute the document
     */
    public METSFileSet getDocumentFiles();

    /**
     *  Obtain the structural information on the document
     *
     *  @return <code>METSStructureSet</code> the structural information on the
     *          document.
     */
    public METSStructureSet getDocumentStructure();

    /**
     *  Indicate whether the document can be stored in a native form in
     *  a METS wrapper
     *
     *  @return <code>boolean</code> <code>true</code> if the document
     *          is just to be wrapped in a METS shell.
     */
    public boolean isMETSCompatible();


    /**
     *  Write the document into a METS wrapper - for many document types,
     *  this will not actually be done by the document itself, but rather
     *  by the default writer
     */
    public DocumentWriter getMETSWriter();

    public DocumentSQLWriter getSQLWriter();
}