001package org.biopax.paxtools.model;
002
003
004import java.io.Serializable;
005import java.util.Map;
006import java.util.Set;
007
008/**
009 * A model acts as a container for BioPAX elements.
010 * Every object within a mode must have unique id.
011 * A single object can be contained in multiple models.
012 */
013public interface Model extends Serializable
014{
015    /**
016     * This method add the given onject to this model. If the object
017     * points to other objects that are not in the model, it is user's
018     * responsibility to add them into the model as well.
019     * If an object with the same id already exists, it will throw
020     * an {@link org.biopax.paxtools.util.IllegalBioPAXArgumentException}
021     *
022     * @param aBioPAXElement to be added
023     */
024
025    void add(BioPAXElement aBioPAXElement);
026
027
028    /**
029     * This method creates a new object using the model's factory, adds it
030     * to the model and returns it.
031     *
032     * @param <T> a BioPAX type
033     * @param aClass the BioPAX model interface class
034     * @param id     of the new object
035     * @return newly created object
036     */
037    <T extends BioPAXElement> T addNew(Class<T> aClass, String id);
038
039    /**
040     * This method returns true if the parameter is contained within
041     * this model. 
042     * 
043     * Note: the result can be 'false' when 
044     * {@link #containsID(String)} is 'true'
045     * (using the URI of the parameter) if, e.g., 
046     * model contains another object with the same URI.
047     * 
048     * @see #containsID(String)
049     *
050     * @param aBioPAXElement to be checked
051     * @return true if the parameter is in the object set
052     */
053    boolean contains(BioPAXElement aBioPAXElement);
054
055    /**
056     * This method returns the biopax element with the given id,
057     * returns null if the object with the given id does not exist
058     * in this model.
059     * @param id of the object to be retrieved.
060     * @return biopax element with the given id.
061     */
062    BioPAXElement getByID(String id);
063
064    /**
065     * This method checks for the biopax element with the given id,
066     * returns true if the object with the given id exists.
067     * in this model.
068     * @param id of the object to be retrieved.
069     * @return biopax element with the given id.
070     */
071    boolean containsID(String id);
072
073
074    /**
075     * This method returns a map of name space prefixes.
076     * This map can be modified.
077     * @return a map, mapping prefixes to full namespaces.
078     */
079    Map<String, String> getNameSpacePrefixMap();
080
081// --------------------- ACCESORS and MUTATORS---------------------
082
083    /**
084     * This method returns a set of objects in the model.
085     * Contents of this set can not be modified.
086     * @return an unmodifiable set of objects.
087     */
088    Set<BioPAXElement> getObjects();
089
090    /**
091     * This method returns a set of objects in the model of the given class.
092     * Contents of this set should not be modified.
093     *
094     * @param <T> a BioPAX type
095     * @param filterBy class to be used as a filter.
096     * @return an unmodifiable set of objects of the given class.
097     */
098    <T extends BioPAXElement> Set<T> getObjects(Class<T> filterBy);
099
100    /**
101     * This method removes the given BioPAX Element from the model.
102     * Other objects in the model can still point to this object.
103     * It is user's responsibility to properly excise these properties.
104     * @param aBioPAXElement to be removed.
105     */
106    void remove(BioPAXElement aBioPAXElement);
107
108    /**
109     * This method sets the factory this model will use for creating
110     * BioPAX objects. For example {@link #addNew(Class, String)} method
111     * uses this factory.
112     *
113     * @param factory this model will use for creating
114     * BioPAX objects.
115     */
116    void setFactory(BioPAXFactory factory);
117
118   /**
119     * This method returns the level of the objects that are
120     * contained within this model.
121     * @return level of the objects within this model.
122     */
123    BioPAXLevel getLevel();
124
125    /**
126     * When set to false, the model will not check for the dependent
127     * objects of a newly added object. When true it will traverse and
128     * add all dependent objects that are not already in the model.
129     * This feature is currently experimental.
130     *
131     * @param value defining the dependency adding behaviour
132     */
133    void setAddDependencies(boolean value);
134
135    /**
136     * When addDependencies is false, the model will not check for the dependent
137     * objects of a newly added object. When true it will traverse and
138     * add all dependent objects that are not already in the model.
139     * This feature is currently experimental.
140     *
141     * @return whether adding dependencies.
142     */
143    boolean isAddDependencies();
144
145    
146    /**
147     * Merges the source model into this one.
148     * 
149     * @param source a model to merge
150     */
151    void merge(Model source);
152    
153    
154    /**
155     * Replaces existing BioPAX element with another one,
156     * of the same or possibly equivalent type,
157     * and updates all the affected references to it (object properties).
158     * 
159     * @param existing object to be replaced
160     * @param replacement the replacement BioPAX object
161     */
162    void replace(BioPAXElement existing, BioPAXElement replacement);
163    
164    
165    /**
166     * Attempts to repair the model,
167     * i.e., make it self-consistent, integral.
168     */
169    void repair();
170
171    
172    /**
173     * Sets the xml:base to use when exporting a BioPAX model.
174     * Usually, is is a data-provider's URI prefix, e.g.,
175     * xml:base="http://www.pantherdb.org/pathways/biopax#" 
176     * Setting this to null makes the exporter print using absolute
177     * URIs (and rdf:about) instead of relative ones (and rdf:ID).
178     * 
179     * @param base a URI prefix or null.
180     */
181     void setXmlBase(String base);
182
183     
184     /**
185      * Gets the model's xml:base (URI prefix/namespace), which
186      * normally the majority of the BioPAX object's absolute URIs
187      * in the model begin with.
188      *
189      * Note: it's not required that all the BioPAX objects
190      * in the model have the same URI prefix/namespace;
191      * e.g., there are can be (and perfectly legal) objects
192      * that use other URI bases, such as http://identifiers.org/,
193      * http://purl.org/, etc. (- usually these are well-known
194      * standard xml bases, or these result from merging several BioPAX
195      * models of different data providers into one model.)
196      *
197      * @return xml:base value
198      */
199     String getXmlBase();
200}