001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.orDocRef
019 */
020
021package org.biojavax;
022import java.util.ArrayList;
023import java.util.Iterator;
024import java.util.List;
025
026import org.biojava.utils.Changeable;
027
028
029/**
030 * Represents an author of a documentary reference.
031 * @author Richard Holland
032 * @see DocRef
033 * @since 1.5
034 */
035public interface DocRefAuthor extends Comparable,Changeable {
036    
037    /**
038     * Returns a textual description of the authors name. This field is
039     * immutable so should be set using the constructor of the implementing class.
040     * @return Value of property name.
041     */
042    public String getName();
043    
044    /**
045     * Returns the extended version of the authors name.
046     * Form: "name (consortium) (ed.)" where sections in brackets are optional.
047     * @return Value of property name with additions.
048     */
049    public String getExtendedName();
050    
051    /**
052     * Is this author actually an editor?
053     * @return true if they are, false if not.
054     */
055    public boolean isEditor();
056    
057    /**
058     * Is this author actually a consortium?
059     * @return true if they are, false if not.
060     */
061    public boolean isConsortium();
062    
063    /**
064     * Useful tools for working with authors.
065     */
066    public static class Tools {
067        
068        // cannot instantiate
069        private Tools() {}
070        
071        /**
072         * Takes a list of authors and returns a set of DocRefAuthor objects.
073         * @param authors a comma-separated list of authors
074         * @return set of DocRefAuthor objects.
075         */
076        public static List<DocRefAuthor> parseAuthorString(String authors) {
077            if (authors==null) throw new IllegalArgumentException("Authors string cannot be null");
078            String[] parts = authors.split("(,|\\sand)\\s+");
079            List<DocRefAuthor> authSet = new ArrayList<DocRefAuthor>();
080            for (int i = 0; i < parts.length; i++) 
081                if(parts[i].length()>0) authSet.add(new SimpleDocRefAuthor(parts[i]));
082            return authSet;
083        }
084        
085        /**
086         * Takes a set of authors and creates a comma-separated string.
087         * For the final comma, it replaces it with the word "and".
088         * @param authors set of authors
089         * @param useAnd whether or not to do the and thing, otherwise
090         * use all commas.
091         * @return a comma-separated string with the word "and" in 
092         * place of the final comma.
093         */
094        public static String generateAuthorString(List<DocRefAuthor> authors, boolean useAnd) {
095            StringBuffer sb = new StringBuffer();
096            int authCount = 1;
097            for (Iterator<DocRefAuthor> i = authors.iterator(); i.hasNext(); ) {
098                DocRefAuthor a = i.next();
099                sb.append(a.getExtendedName());
100                if (i.hasNext()) {
101                    if (authCount++==authors.size()-1 && useAnd) sb.append(" and ");
102                    else sb.append(", ");
103                }
104            }
105            return sb.toString();
106        }        
107    }
108    
109}