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}