// BibRef.java // // senger@ebi.ac.uk // March 2001 // /* * BioJava development code * * This code may be freely distributed and modified under the * terms of the GNU Lesser General Public Licence. This should * be distributed with the code. If you do not have a copy, * see: * * http://www.gnu.org/copyleft/lesser.html * * Copyright for this code is held jointly by the individual * authors. These should be listed in @author doc comments. * * For more information on the BioJava project and its aims, * or to join the biojava-l mailing list, visit the home page * at: * * http://www.biojava.org/ * */ package org.biojava.bibliography; import java.util.Hashtable; /** *

* This class is a core class of the bibliographic data model - it * represents a bibliographic reference, a citation. * It is a super-class for all specialized citation types, but it * can also be instantiated and represent an additional specialized * citation type. *

* *

* The BibRef class has several explicit attributes, which are * reasonably general and which originate from the * Dublin Core Metadata, and a * hashtable that can hold any number of additional attributes. The same pattern is * repeatedly used on several other places of the data model. It achieves * extendibility without losing interoperability if the following rules are obeyed: *

*

* *

* The BibRef class is a parent class for derived classes representing bibliographic * references to specialized bibliographic resources. The following classes are * defined explicitly: * {@link BiblioBook}, * {@link BiblioArticle}, * {@link BiblioBookArticle}, * {@link BiblioJournalArticle}, * {@link BiblioPatent}, * {@link BiblioThesis}, * {@link BiblioProceeding}, * {@link BiblioTechReport}, and * {@link BiblioWebResource} *

* *

* The active participants of the process of creation and dissemination of the * bibliographic resources are defined by the class {@link BiblioProvider} and its * sub-classes. The participants can be people, organizations, or even software * services (mainly used for new digital resources). The most obvious examples * are authors, but it includes also publishers and other contributors. *

* *

* And finally, there is a class {@link BiblioJournal} describing journals. * The citations referring to the journal articles have a reference to this class. *

* *

* This is an overview of all participating classes and their attributes: * . *

* * @author Martin Senger * @version $Id: BibRef.java 2812 2003-07-16 16:01:11Z mrp $ * @since 1.3 */ public class BibRef { /** * Additional attributes of this citation. */ public Hashtable properties = new Hashtable(); /** It is an unambiguous reference to this citation "within the world". * It is a string conforming to an identification system. An example * of such system can be a combination of a well-known repository name * and a unique identifier defined within this repository, such as * MEDLINE/20000003. */ public String identifier; /** *

* It defines the nature or genre of the cited resource. *

* *

* A recommended best practice is to use only values from a controlled vocabulary * named as defined in {@link BibRefSupport#RESOURCE_TYPES}. * Syntactically, and because of making query navigation easier, the value of this * attribute should be equal to a constant predefined in {@link BibRefSupport}, * such as {@link BibRefSupport#TYPE_BOOK} for books, or * {@link BibRefSupport#TYPE_JOURNAL_ARTICLE} for journal articles. * However, there may be bibliographic resources, which are * not defined by specialized sub-classes (for example, letters, practical guideline, * or archives), and therefore they do not have predefined names in * {@link BibRefSupport} interface. *

* *

* Note that for the description of the physical or digital manifestation of the * cited resource there is an attribute {@link #format}. *

*/ public String type; /** *

* It is an array of identifiers, all of them pointing to the same cited source * but usually stored in different bibliographic repositories. *

* *

* Note that this attribute is not for referencing citations to other documents * that are related to the cited document. *

*/ public String[] crossReferences; /** * A title given to the cited resource (a name by which the resource is formally known). */ public String title; /** * It defines the topic of the content of the cited resource. */ public BiblioSubject subject; /** * An account of the content of the cited resource. * It is either an abstract, or table of contents, or both. * It can be written in a language different from the language of the cited resource. */ public BiblioDescription description; /** * It defines an extent or scope of the content of the cited resource. * It can include spatial location (a place name or geographic co-ordinates), * temporal period (a period label, date, or date range), or both. */ public BiblioScope coverage; /** *

* The authors and contributors are responsible for creating the contents of the cited resource. * There is no formal definition of how this responsibility is divided between them. However, * the authors are usually primary creators while contributors may be illustrators, translators, * or other creative providers. *

* *

* The authors are in an ordered array (to be able to find the first author). *

*/ public BiblioProvider[] authors; /** *

* The authors and contributors are responsible for creating the contents of the cited resource. * There is no formal definition of how this responsibility is divided between them. However, * the authors are usually primary creators while contributors may be illustrators, translators, * or other creative providers. *

* *

* The contributors are in an ordered array (to be able to find the first contributor). *

*/ public BiblioProvider[] contributors; /** * A publisher is responsible for making the resource available. */ public BiblioProvider publisher; /** *

* It specifies information about rights over the cited resource. * Typically, it contains a rights management statement for the resource, or it refers * to a service providing such information. Rights information often encompasses * Intellectual Property Rights, * Copyright, and various Property Rights. *

* *

* If the attribute is empty, no assumptions can be made about the status of these and * other rights with respect to the cited resource. *

*/ public String rights; /** *

* Defines a date associated with an event in the life cycle of the cited resource * when this resource became available. Usually, it is a date of publishing. However, * for not yet published resources, it can be a date of creation. *

* *

* The suggested encoding is as defined in a W3C NOTE * Date and Time Formats. * This NOTE defines a profile of ISO8601 standard. * ISO8601 describes a large number of date/time formats and the NOTE reduces the scope and restricts * the supported formats to a small number. The profile offers a number of options from which this * attribute should contain/permit only the following ones: *

* *

*

*
Year *
YYYY (e.g., 2000) *
Year and month *
YYYY-MM (e.g., 2000-12) *
Complete date *
YYYY-MM-DD (e.g., 2000-12-31) *
Complete date plus hours, minutes, and seconds *
YYYY-MM-DDThh:mm:ssZ (e.g., 2000-12-31T23:59:59Z) *
*

* *

* Exactly the components shown here must be present, with exactly this punctuation. * Note that the T appears literally in the string, to indicate the beginning * of the time element, as specified in ISO 8601. *

* *

* Times are expressed in UTC (Coordinated Universal Time), with a special UTC designator * (Z), again as specified in ISO 8601. *

* *

* For query purposes, the format with fewer details is considered * as having all possible values in place of missing details. Thus, YYYY-MM would mean * all dates and times in the given month. *

*/ public String date; /** *

* It defines a language of the intellectual contents of the cited resource. * The recommendation is to use values as defined by * RFC1766 which includes a two-letter * Language Code (taken from the ISO639 standard), followed optionally by a two-letter * Country Code (taken from the ISO3166 standard). *

* *

* For example, en for English, * fr for French, or en-uk for English used in the United Kingdom. *

* *

* Another possibility is to use * MARC List of Languages. *

* *

* In any case, the name of the used controlled vocabulary should be equal to * {@link BibRefSupport#LANGUAGES}. *

*/ public String language; /** * It describes the physical or digital manifestation of the cited * resource. It can have very different content depending on the * citation type. Therefore, it is highly recommended to use a * controlled vocabulary to fill this attribute. The name of such * vocabulary should be equal to the type of the reosurce type * followed by {@link BibRefSupport#ATTR_FORMAT}. For example: * {@link BibRefSupport#TYPE_BOOK}/{@link BibRefSupport#ATTR_FORMAT}. */ public String format; /** * It defines information related to the citation itself rather than to the cited resource. */ public BiblioEntryStatus entryStatus; }