org.biojava.bibliography.BibRef Maven / Gradle / Ivy
// BibRef.java
//
// [email protected]
// 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 implementation must be prepared for cases when the explicitly
* defined attributes are empty (containing null value, or,
* in case of arrays, an empty list of elements).
*
- The names of additional properties (keys of the hashtable) must be
* obtainable and/or checkable using controlled vocabularies
* (see interface {@link BibRefSupport} for details).
*
- The values stored in that hashtable should be of "reasonable" types. Any
* implementation should understand at least basic Java types (in most cases
* the String type is the best choice). The more exotic types
* are used, the less interoperability between implementations is likely.
*
*
*
*
* 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$
* @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;
}