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

package org.greenstone.gsdl3.gs3build.doctypes;

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

import java.net.URL;

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

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

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();

  /**
   *  Get the date that this file was modified
   */
  public long getModifiedDatestamp();

  /**
   *  Check if the document matches another in the database
   */
  public boolean hasDuplicate(GS3SQLConnection connection);
    
  /**
   *  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 document as a dom object
   */
  public org.w3c.dom.Document getDOMDocument();

  /**
   *  Get the text of a section of this document
   *
   *  @return <code>String</code> the text as a string - for sections
   *          that have no textual components, this value may be
   *          <code>null</code>
   */
  public String getSectionText(String sectionId);
    
  /**
   *  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 a particular given upon the document, encoded as a <code>List</code>
   *
   *  @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>MetadataLabel</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(MetadataLabel label, String value);
  
  /**
   *  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>MetadataLabel</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 setDocumentMetadata(MetadataLabel 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);

  /**
   *  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 setDocumentMetadata(String namespace, String label, String value);

  /**
   *  Facilitate the removal of document metadata.
   *
   *  @param <code>String</code> namespace of the metadata
   *  @param <code>String</code> label of the metadata, with a '.' to deliminate
   *                             sub-component structures
   */
  public void removeDocumentMetadata(String namespace, String label);
  
  /**
   *  Facilitate the removal of all metadata of a given label from the document.
   *
   *  @param <code>String</code> namespace of the metadata
   *  @param <code>String</code> label of the metadata, with a '.' to deliminate
   *                             sub-component structures
   */
  public void removeAllMetadata(String namespace, String label);
  
  /**
   *  Post metadata to a file in this document - the appropriate changes
   *  should be made...
   *
   *  @param <code>URL</code> the location of the file...
   *  @param <code>String</code> the 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 postFileMetadata(URL fileLocation, 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();

  /**
   *  Set the constituent files for the document.
   */
  public void setDocumentFiles(METSFileSet fileSet);

  /**
   *  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();
  
  /**
   *  Get the writer to send the document to an SQL database
   */
  public DocumentSQLWriter getSQLWriter();

  /**
   *  Check if the document is changed or not
   */
  public boolean isModified();

  /**
   *  Set the document modified state
   */
  public void setModified(boolean isModified);
}