article.java

一个自然语言处理的Java开源工具包。LingPipe目前已有很丰富的功能

/*
 * LingPipe v. 3.5
 * Copyright (C) 2003-2008 Alias-i
 *
 * This program is licensed under the Alias-i Royalty Free License
 * Version 1 WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the Alias-i
 * Royalty Free License Version 1 for more details.
 *
 * You should have received a copy of the Alias-i Royalty Free License
 * Version 1 along with this program; if not, visit
 * http://alias-i.com/lingpipe/licenses/lingpipe-license-1.txt or contact
 * Alias-i, Inc. at 181 North 11th Street, Suite 401, Brooklyn, NY 11211,
 * [phone].
 */

package com.aliasi.medline;

import com.aliasi.xml.DelegateHandler;
import com.aliasi.xml.DelegatingHandler;
import com.aliasi.xml.TextAccumulatorHandler;

import java.util.Arrays;
import java.util.ArrayList;
import java.util.List;

import org.xml.sax.Attributes;
import org.xml.sax.SAXException;

import org.xml.sax.helpers.DefaultHandler;

/**
 * An <code>Article</code> represents the content of the
 * <code>Article</code> element of a MEDLINE citation.
 *
 * <P>An article contains information about the journal in
 * which it is published.  
 *
 * <P>Each article is required to have a title, and its text
 * is returned by the method {@link #articleTitle()}.  Each article
 * also has information about its page numbers within the 
 * journal in which it was published, which is returned by
 * the methods {@link #pagination()} and {@link #eLocationIds()}.
 * There will be a pagination and zero or more e-locations,
 * or there will be one or more e-locations for each article.
 *
 * <P>An article optionally contains an abstract, which will be a
 * non-<code>null</code> return value from {@link #abstrct()}; note the
 * unusual argument naming to avoid conflict with the keyword
 * <code>abstract</code>.
 *
 * <P>Articles also optionally contain an author list and affiliation
 * for the first author, which will be available as a non-null return
 * values from {@link #authorList()} and {@link #affiliation()}.
 *
 * <P>One or more languages in which the text of the article appeared
 * is available from {@link #languages()}.  Note that abstracts, if
 * available, are always in English.  For articles not in English,
 * the {@link #vernacularTitle()} method returns the original title
 * transliterated into the Roman alphabet; for English articles, it
 * returns the empty string.
 *
 * <P>Some articles contain linkages to sequence databanks.  The
 * method {@link #dataBankList()} returns a list of zero or more
 * such linkages, organized by database.
 *
 * <P>Some articles contain information about grant funding for
 * the research reported.  The method {@link #grantList()} returns
 * zero or more grant objects.
 *
 * <P>Each article contains a non-empty list of publication types,
 * available through {@link #publicationTypes()}.
 *
 * <P>Articles that were published electronically as well as in print
 * also specify the electronic publication date as a
 * non-<code>null</code> value for {@link #articleDate()}.
 *
 * @author  Bob Carpenter
 * @version 3.6
 * @since   LingPipe2.0
 */
public class Article {
    private final String mPublicationModel;
    private final Journal mJournal;
    private final String mArticleTitle;
    private final String mPagination;
    private final ELocationId[] mELocationIds;
    private final Abstract mAbstract;
    private final String mAffiliation;
    private final AuthorList mAuthorList;
    private final String[] mLanguages;
    private final DataBankList mDataBankList;
    private final GrantList mGrantList;
    private final String[] mPublicationTypes;
    private final String mVernacularTitle;
    private final ArticleDate mArticleDate;
    Article(String publicationModel,
            Journal journal,
            String articleTitle,
            String pagination,
            ELocationId[] eLocationIds,
            Abstract abstrct,
            String affiliation,
            AuthorList authorList,
            String[] languages,
            DataBankList dataBankList,
            GrantList grantList,
            String[] publicationTypes,
            String vernacularTitle,
            ArticleDate articleDate) {
        mPublicationModel = publicationModel;
        mJournal = journal;
        mArticleTitle = articleTitle;
        mPagination = pagination;
        mELocationIds = eLocationIds;
        mAbstract = abstrct;
        mAffiliation = affiliation;
        mAuthorList = authorList;
        mLanguages = languages;
        mDataBankList = dataBankList;
        mGrantList = grantList;
        mPublicationTypes = publicationTypes;
        mVernacularTitle = vernacularTitle;
        mArticleDate = articleDate;
    }

    /**
     * Returns the publication model for this article.  All articles
     * have one of the following models:
     *
     * <blockquote>
     * <table border='1' cellpadding='5'>
     * <tr><td><i>Publication Type</i></td><td><i>Constant</i></td></tr>
     * <tr><td>Print</td><td><code>MedlineCitationSet.PRINT_VALUE</td></tr>
     * <tr><td>Print-Electronic</td><td><code>MedlineCitationSet.PRINT_ELECTRONIC_VALUE</td></tr>
     * <tr><td>Electronic</td><td><code>MedlineCitationSet.ELECTRONIC_VALUE</td></tr>
     * <tr><td>Electronic-Print</td><td><code>MedlineCitationSet.ELECTRONIC_PRINT_VALUE</td></tr>
     * </table>
     * </blockquote>
     */
    public String publicationModel() {
        return mPublicationModel;
    }

    /**
     * Returns the page numbering for this article as a string, or <code>null</code>
     * if there is no page numbering for this article if it is electronic only.
     * Articles without pagination must have at least one electronic location
     * identifier, returned by method {@link #eLocationIds()}.
     *
     * <p>The
     * pagination is presented without redundant prefixes; for example
     * <code>212-27</code> indicates pages 212 to 227.  MEDLINE
     * presents a wide range of possible pagination schemes.  There
     * may be be alphanumeric page numbering (<i>e.g.</i>
     * <code>P32-4</code>), split pages (<i>e.g.</i> <code>24-32,
     * 64</code>), pages plus sections (<i>e.g.</i> <code>176-8
     * concl</code> <i>or</i> <code>suppl 111-2</code>), Roman
     * numerals (<i>e.g.</i> <code>iii-viii</code> <i>or</i>
     * <code>XC-CIII</code>), or other descriptive content
     * (<i>e.g.</i> <code>1 p preceding table of contents</code>
     * <i>or</i> <code>[6021 words; 81 paragraphs]</code>).
     *
     * @return The page numbering for this article as a string.
     */
    public String pagination() {
        return mPagination;
    }

    /**
     * Returns zero or more electronic location identifiers for this
     * article.  If the return value of {@link #pagination()} is
     * <code>null</code>, then the list returned by this method will
     * contain at least one element.  If pagination is not null, the
     * array of electronic locations may have zero or more elements.
     *
     * @return The electronic location identifiers for this article.
     */
    public ELocationId[] eLocationIds() {
        return mELocationIds;
    }

    /**
     * Returns a representation of the journal in which this article
     * appeared.
     *
     * @return The journal in which this article was published.
     */
    public Journal journal() {
        return mJournal;
    }


    /**
     * Returns the title of this article.  Article titles are always
     * returned in English.  A translated title appears wrapped in
     * square brackets (<i>e.g.</i>. <code>[Biological rhythms and
     * human disease]</code> <i>or</i> <code>[Anterior
     * panhypopituitarism after sella turcica fracture (author's
     * trans)]</code>).  Note that if the citation is in process, the
     * title will appear as <code>[In Process Citation]</code>.
     * Untranslated titles end with a period unless the article title
     * itself ends with another punctuation mark (<i>e.g.</i>
     * <code>Why is xenon not more widely used for anaesthesia?</code>
     * <i>or</i> <code>The Kleine-Levin syndrome as a neuropsychiatric
     * disorder: a case report.</code>).
     *
     * @return The title of this article.
     */
    public String articleTitle() {
        return mArticleTitle;
    }

    /**
     * Returns <code>true</code> if the article has been translated
     * from a language other than English.  The method determines this
     * by inspecting the article title for marking that it has been
     * translated.
     *
     * @return <code>true</code> if the article has been
     * translated from a language other than English.
     */
    public boolean articleTranslated() {
        return articleTitle().length() > 1
            && articleTitle().charAt(0) == '['
            && articleTitle().charAt(articleTitle().length()-1) == ']';
    }

    /**
     * Return the article title without any brackets that may have
     * been added to indicate translation and without any indication
     * of the author having translated it.  Note that sentence-final
     * periods may have also been inserted by NLM, but there is no
     * reliable way to remove them without potentially removing
     * periods that ended original titles, such as those ending
     * acronyms.
     *
     * @return The text of the title of th is article.
     */
    public String articleTitleText() {
        if (!articleTranslated()) return articleTitle();
        String baseText
            = articleTitle().substring(1,articleTitle().length()-1);
        if (baseText.endsWith(AUTHORS_TRANS_MARKER))
            return baseText.substring(0,
                                      baseText.length()
                                      - AUTHORS_TRANS_MARKER.length());
        return baseText;
    }

    /**
     * Returns the abstract for this article, or <code>null</code> if
     * there is no abstract.
     *
     * @return The abstract for this article.
     */
    public Abstract abstrct() {
        return mAbstract;
    }

    /**
     * Returns the author list for this article. Note that this
     * list will not be null, but may be empty.  This varies
     * slightly from the XML, which simply elides the author list
     * when it has no members, as in the case of an anonymous
     * article.
     *
     * @return The author list for this article.
     */
    public AuthorList authorList() {
        return mAuthorList;
    }

    /**
     * Returns the affiliation for the the first author of this
     * article.  The way in which affiliation is recorded has evolved
     * from its introduction in 1988.  At one point, it included city
     * information along with state and zip code information for the
     * United States and country information for elsewhere.  Later it
     * added the <code>USA</code> for United States-based
     * institutiones. In 1996, the email was added as it appears in
     * the article. As of 2003, first author address is included as it
     * appears in the article.
     *
     * @return Affiliation information for first author.
     */
    public String affiliation() {
        return mAffiliation;
    }