001package org.biopax.paxtools.model.level3;
002
003import java.util.Set;
004
005/**
006 * Interface for all classes that can have names in BioPAX. All named BioPAX elements can have
007 * multiple names, and exactly one standardName and exactly one shortName. standardName and
008 * shortName are OWL subproperties of name in BioPAX, so these are automatically considered as a
009 * name if defined. Paxtools refle
010 * 
011 * Warning: There is a potential OWL-JAVA semantic mismatch when manipulating names. If a user
012 * decides to assign a different name to standardName or shortName, what happens to the old name is
013 * not well defined - they can be "demoted" to a regular name or removed from the names list
014 * altogether. Paxtools currently does the latter. If this is not the desired behaviour, the old
015 * name should be added manually back to the names list.
016 */
017public interface Named extends XReferrable
018{
019        /**
020         * Names for this entity, including standardName and shortName if defined.
021         * 
022         * The contents of this set can be modified directly but semantic consistency is not guaranteed.
023         * Using {@link #addName} and {@link #removeName} is recommended.
024         *
025         * @return Names for this entity, including standardName and shortName if defined.
026         */
027        public Set<String> getName();
028
029
030        /**
031         * This method is reserved for batch operations and should not be used for normal use.
032         * Use add/remove name methods to manipulate the names instead.
033         *
034         * @param names new names to set (or replace all existing ones)
035         */
036        public void setName(Set<String> names);
037
038        /**
039         * This method adds the given value to the name set.
040         *
041         * @param name a new name to be added
042         */
043        public void addName(String name);
044
045        /**
046         * This method removes the given value from the name set.
047         *
048         * @param name a new name to be removed
049         */
050        public void removeName(String name);
051
052
053        /**
054         * An abbreviated name for this entity, preferably a name that is short enough to be used in a
055         * visualization application to label a graphical element that represents this entity. If no short
056         * name is available, an xref may be used for this purpose by the visualization application.
057         *
058         * @return An abbreviated name for this entity
059         */
060        public String getDisplayName();
061
062
063        /**
064         * An abbreviated name for this entity, preferably a name that is short enough to be used in a
065         * visualization application to label a graphical element that represents this entity. If no short
066         * name is available, an xref may be used for this purpose by the visualization application.
067         *
068         * @param displayName new display name (preferably a short one)
069         */
070        public void setDisplayName(String displayName);
071
072
073
074        /**
075         * The preferred full name for this entity, if exists assigned by a standard nomenclature
076         * organization such as HUGO Gene Nomenclature Committee.
077         *
078         * @return standard name for this entity
079         */
080        String getStandardName();
081
082
083        /**
084         * The preferred full name for this entity, if exists assigned by a standard nomenclature
085         * organization such as HUGO Gene Nomenclature Committee.
086         *
087         * @param standardName standard name for this entity
088         */
089        public void setStandardName(String standardName);
090
091}