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.org/
019 *
020 */
021
022package org.biojavax;
023
024import java.net.URI;
025
026import org.biojava.utils.ChangeType;
027import org.biojava.utils.ChangeVetoException;
028import org.biojava.utils.Changeable;
029
030/**
031 * The namespace of an entry in a database schema. Relates directly to the
032 * BioDatabase table in BioSQL. All BioEntry objects belong to namespaces.
033 * @author Mark Schreiber
034 * @author Richard Holland
035 * @see org.biojavax.bio.BioEntry
036 * @since 1.5
037 */
038public interface Namespace extends Comparable,Changeable {
039    
040    public static final ChangeType NAME = new ChangeType(
041            "This namespace's name has changed",
042            "org.biojavax.Namespace",
043            "NAME"
044            );
045    public static final ChangeType AUTHORITY = new ChangeType(
046            "This namespace's authority has changed",
047            "org.biojavax.Namespace",
048            "AUTHORITY"
049            );
050    public static final ChangeType DESCRIPTION = new ChangeType(
051            "This namespace's description has changed",
052            "org.biojavax.Namespace",
053            "DESCRIPTION"
054            );
055    public static final ChangeType ACRONYM = new ChangeType(
056            "This namespace's acronym has changed",
057            "org.biojavax.Namespace",
058            "ACRONYM"
059            );
060    public static final ChangeType URI = new ChangeType(
061            "This namespace's URI has changed",
062            "org.biojavax.Namespace",
063            "URI"
064            );
065    
066    /**
067     * The name of the namespace is immutable and must be set by the constructor
068     * of the instantiating class. The name should also be unique. This method
069     * will return the name.
070     * @return The name of the namespace.
071     */
072    public String getName();
073    
074    /**
075     * This method will return the authority that governs the namespace.
076     * @return the name of the namespace authority.
077     */
078    public String getAuthority();
079    
080    /**
081     * This method sets the authority that governs the namespace. Null will 
082     * unset it. 
083     * @param authority the name of the namespace authority.
084     * @throws ChangeVetoException in case of objections.
085     */
086    public void setAuthority(String authority) throws ChangeVetoException;
087    
088    /**
089     * Returns a description of this namespace.
090     * @return the description of the namespace.
091     */
092    public String getDescription();
093    
094    /**
095     * This method sets a description for the namespace. Null will unset it. 
096     * @param description the description of the namespace.
097     * @throws ChangeVetoException in case of objections.
098     */
099    public void setDescription(String description) throws ChangeVetoException;
100    
101    /**
102     * If the namespace has an acronym, this will return it.
103     * @return the acronym for the namespace.
104     */
105    public String getAcronym();
106    
107    /**
108     * Sets an optional acronym for the namespace. Null will unset it. Note that
109     * in BioSQL 1.0 Acronym is only part of the Oracle schema therefore it will
110     * only be persisted in that schema.
111     * @param acronym the acronym for the namespace.
112     * @throws ChangeVetoException in case of objections.
113     */
114    public void setAcronym(String acronym) throws ChangeVetoException;
115    
116    /**
117     * If the namespace has a URI, this will return it.
118     * @return the URI of the authority.
119     */
120    public URI getURI();
121    
122    /**
123     * Sets an optional URI for the namespace. Null will unset it. Note that in
124     * BioSQL 1.0 URI is not persisted into the database unless the 
125     * extended Oracle schema is used.
126     * @param URI the URI of the authority.
127     * @throws ChangeVetoException in case of objections.
128     */
129    public void setURI(URI URI) throws ChangeVetoException;
130    
131}
132