cdmlib-model/src/main/java/eu/etaxonomy/cdm/model/common/IOriginalSource.java

   1 // $Id$
   2 /**
   3  * Copyright (C) 2007 EDIT
   4  * European Distributed Institute of Taxonomy
   5  * http://www.e-taxonomy.eu
   6  *
   7  * The contents of this file are subject to the Mozilla Public License Version 1.1
   8  * See LICENSE.TXT at the top of this package for the full license terms.
   9  */
  10
  11 package eu.etaxonomy.cdm.model.common;
  12
  13 import eu.etaxonomy.cdm.model.reference.Reference;
  14
  15 /**
  16  * An original source can be used in different ways.<BR>
  17  * 1.) As a referencing system. The original source holds all information about the reference,
  18  * the microReference (page, figure, ...), the identifier used in the source for the referenced object in the
  19  * reference, a namespace that makes this identifier unique, the original name string that in
  20  * general stores the representation of the referenced object within the source (if the string representation
  21  * in the source differs from that one unsed in the CDM object)
  22  *
  23  * 2.) Dataprovenance: When importing data from another datasource important information like the identifier
  24  * and it's namespace (e.g. tablename) as well as the datasource itself maybe stored in an original source.
  25  * E.g. when importing SDD data here you may store the filename and the id used in the SDD file here.
  26  *
  27  * Starting with v3.3 we started to let this class be influenced by the PROV Ontology
  28  * (http://www.w3.org/TR/2013/NOTE-prov-overview-20130430/). It may move further in this direction in
  29  * future.
  30  * The above mentioned ways to use the Original Source are now related to different activity types
  31  * (http://www.w3.org/TR/2013/REC-prov-dm-20130430/#term-Activity) in PROV.
  32  *
  33  *
  34  * @author a.mueller
  35  * @created 18.09.2009
  36  */
  37 public interface IOriginalSource<T extends ISourceable> {
  38
  39         /*************** GETTER /SETTER ************************************/
  40
  41
  42         /**
  43          * Returns the {@link OriginalSourceType type} of the source. The type defines the relationship
  44          * between the current data and the original data.
  45          * @see OriginalSourceType
  46          * @return the type of the source
  47          */
  48         public OriginalSourceType getType();
  49
  50         /**
  51          * @see #getType()
  52          * @param type the type to be set
  53          */
  54         public void setType(OriginalSourceType type);
  55
  56         /**
  57          * Returns the (unique) identifier used in the source.
  58          * If the identifier is not unique, {@link #getIdNamespace() namespace} should be defined.
  59          * The namespace together with the identifier should be unique.
  60          * @return  the identifier used in the source.
  61          */
  62         public String getIdInSource();
  63
  64         /**
  65          * @see #getIdInSource()
  66          * @param idInSource
  67          */
  68         public void setIdInSource(String idInSource);
  69
  70         /**
  71          * Returns the id namespace. The id namespace is a String that further defines the origin of
  72          * the original record. In the combination with the id it should be unique within one a source.
  73          * E.g. if a record comes from table ABC and has the id 345, 'ABC' is a suitable namespace and the
  74          * combination of 'ABC' and 345 is a unique id for this source.
  75          * The namespace is meant to distinguish import records that come from two different tables, elements, objects, ...
  76          * and end up in the same CDM class. In this case the id may not be enough to identify the original record.
  77          * @return the idNamespace
  78          */
  79         public String getIdNamespace();
  80
  81         /**
  82          * @see #getIdNamespace()
  83          * @param idNamespace the idNamespace to set
  84          */
  85         public void setIdNamespace(String idNamespace);
  86
  87         /**
  88          * The object this original source is the source for
  89          * @return
  90          */
  91         public T getSourcedObj();
  92
  93         /**
  94          * @see #getSourcedObj()
  95          * @param sourcedObj
  96          */
  97         public void setSourcedObj(T sourcedObj);
  98
  99         /**
 100          * Returns the micro citation of the according citation. This may be a String
 101          * defining a page or a page range, a figure in a citation, etc.
 102          * Examples: 'p.345', 'pp.345-367', 'fig. 3a', ...
 103          * @return
 104          */
 105         public String getCitationMicroReference();
 106
 107         /**
 108          * @see #getCitationMicroReference()
 109          * @param microCitation
 110          */
 111         public void setCitationMicroReference(String microCitation);
 112
 113
 114         /**
 115          * Returns the citation.
 116          * @return
 117          */
 118         public Reference getCitation();
 119
 120         /**
 121          * @see #getCitation()
 122          * @param citation
 123          */
 124         public void setCitation(Reference citation);
 125
 126 }