001package org.biopax.paxtools.controller;
002
003import org.biopax.paxtools.model.BioPAXElement;
004import org.biopax.paxtools.model.BioPAXLevel;
005
006import java.util.Iterator;
007import java.util.Set;
008
009/**
010 * This class contains methods that eases to use editors for
011 * specific or a set of property. Using the methods of this class
012 * editors of a class, editors of a property, and editors of a property
013 * with the given domain can be obtained; and these editors/this editor
014 * can be used to modify object's properties.
015 *
016 * The functionallity of this class plays key roles on several other classes'
017 * functionallity; e.g. {@link org.biopax.paxtools.io}, {@link org.biopax.paxtools.model},
018
019 */
020public interface EditorMap
021{
022
023// -------------------------- OTHER METHODS --------------------------
024
025    /**
026     * This method returns the <em>editor</em> intended to handle
027     * property named <em>property</em> of a class (<em>javaClass</em>).
028     * This editor can then be used to modify the property of
029     * an element of class <em>javaClass</em>.
030     *
031     * To put in other words, this methods returns the editor of which
032     * domain includes <em>javaClass</em>, and the editor that can handle
033     * the <em>property</em>.
034     *
035     * @param property name of the property for which editor will be called
036     * @param javaClass class of the element
037     * @param <D> domain
038     * @return null if there is no such editor
039     */
040        <D extends BioPAXElement> PropertyEditor<? super D,?> getEditorForProperty(String property, Class<D> javaClass);
041
042    /**
043     * This method returns the set of <em>editor</em>s intended to handle
044     * property named <em>property</em>. This editor can then be used
045     * to modify the property of an element which is in editor's domain list.
046     *
047     * In other words, this methods returns the set of the editors
048     * that can handle the <em>property</em>. Editors are not filtered for
049     * a specific domain class.
050     *
051     * @param property name of the property for which editor will be called
052     * @return empty set if there are no such editors
053     */
054    Set<PropertyEditor> getEditorsForProperty(String property);
055
056        /**
057          * This method returns the set of <em>editor</em>s intended to handle
058          * property named <em>property</em>. This editor can then be used
059          * to modify the property of an element which is in editor's domain list.
060          *
061          * In other words, this methods returns the set of the editors
062          * that can handle the <em>property</em>. Editors are not filtered for
063          * a specific domain class.
064          *
065          * @param property name of the property for which editor will be called
066          * @param domain biopax type/class the property belongs to
067          * @param <D> domain biopax type
068          * @return empty set if there are no such editors
069          */
070
071        public <D extends BioPAXElement> Set<PropertyEditor<? extends D, ?>> getSubclassEditorsForProperty(
072                        String property, Class<D> domain);
073
074        /**
075     * This method returns the set of <em>editor</em>s whose domain
076     * subsumes the class of given BioPAX element.
077     *
078         * @param bpe BioPAX element for which the available editors will be returned
079         * @return empty set if there are no such editors
080     */
081    Set<PropertyEditor> getEditorsOf(BioPAXElement bpe);
082
083        /**
084         * Properties in BioPAX specification is unidirectional. e.g. entityReference property that links a
085         * PhysicalEntity to EntityReference has no defined corresponding inverse property that links
086         * EntityReferences to their corresponding entities.
087         *
088         * Most OWL reasoners can query the inverse of a property at no additional cost, but for most OO implementations
089         * this would require an expensive O(n) lookup.
090         * An OO implementation requires keeping additional properties for efficiency purposes.
091         * Inverse editors are read-only editors that captures these "inverse" part of the bidirectional properties
092         * specifically implemented in Paxtools. They have the pattern <em>PropertyName</em>Of  e.g. entityReferenceOf.
093         * @param bpe  BioPAX element for which the available inverse editors will be returned.
094         * @return all inverse editors  for this entity's class type.
095         */
096        Set<ObjectPropertyEditor> getInverseEditorsOf(BioPAXElement bpe);
097
098
099    /**
100     * Returns a set of sub classes of a given class. This method
101     * can be used for class filtering methods.
102     *
103     * @param javaClass the class whose subclasses will be returned
104     * @param <E> biopax type (biopax object model interface)
105     * @return an empty set if there are no such editors
106     */
107    <E extends BioPAXElement> Set<? extends Class<E>> getKnownSubClassesOf(Class<E> javaClass);
108
109
110    /**
111     * Returns the BioPAX level for which editor map is created. Different
112     * BioPAX levels have different editor maps.
113     *
114     * @return BioPAX Level
115     */
116    BioPAXLevel getLevel();
117
118        /**
119         * This method returns the set of <em>editor</em>s whose domain
120         * subsumes the given class
121         *
122         * @param domain BioPAX model interface for which the available editors will be returned
123         * @return empty set if there are no such editors
124         */
125        Set<PropertyEditor> getEditorsOf(Class<? extends BioPAXElement> domain);
126
127        /**
128         * Properties in BioPAX specification is unidirectional. e.g. entityReference property that links a
129         * PhysicalEntity to EntityReference has no defined corresponding inverse property that links
130         * EntityReferences to their corresponding entities.
131         *
132         * Most OWL reasoners can query the inverse of a property at no additional cost, but for most OO implementations
133         * this would require an expensive O(n) lookup.
134         * An OO implementation requires keeping additional properties for efficiency purposes.
135         * Inverse editors are read-only editors that captures these "inverse" part of the bidirectional properties
136         * specifically implemented in Paxtools. They have the pattern <em>PropertyName</em>Of  e.g. entityReferenceOf.
137         * @param domain of the inverse property
138         * @return all inverse editors  for this class type.
139         */
140        Set<ObjectPropertyEditor> getInverseEditorsOf(Class<? extends BioPAXElement> domain);
141
142        /**
143         * @return An iterator over all the properties in this EditorMap
144         */
145        public Iterator<PropertyEditor> iterator();
146
147}