001package org.biopax.paxtools.io;
002
003import org.biopax.paxtools.controller.EditorMap;
004import org.biopax.paxtools.model.BioPAXFactory;
005import org.biopax.paxtools.model.BioPAXLevel;
006import org.biopax.paxtools.model.Model;
007
008import java.io.FileNotFoundException;
009import java.io.InputStream;
010import java.io.OutputStream;
011
012/**
013 * This interface defines IO related operations that can be performed on
014 * BioPAX models.
015 */
016public interface BioPAXIOHandler
017{
018
019 /**
020  * This option is only applicable two level 2 models.
021  * When enabled it will replicate illegally reused
022  * pysicalEntityParticipants in Level2 files.
023  * @param fixReusedPEPs true or false
024  */
025 void fixReusedPEPs(boolean fixReusedPEPs);
026
027 /**
028  * This flag will fix a common legacy bug from BioCyc where the "NIL" string
029  * was used for representing unknown values.
030  * @param treatNILasNull true or false
031  */
032 void treatNilAsNull(boolean treatNILasNull);
033
034 /**
035  * This method will read the OWL document given by the input stream
036  * and will convert it into an in memory BioPAX model.
037  * @param in a BioPAX data input stream (RDF/XML format)
038  * @return new BioPAX object Model
039  */
040 Model convertFromOWL(InputStream in);
041
042 /**
043  * This method will read multiple OWL document
044  * and will merge them into an in memory BioPAX model.
045  * @param files input BioPAX files (RDF/XML)
046  * @return new BioPAX object model
047  * @throws FileNotFoundException when a file does not exist.
048  */
049 Model convertFromMultipleOwlFiles(String... files)
050   throws FileNotFoundException;
051
052 /**
053  * This method will write the model to the output stream. Default encoding
054  * is RDF/XML.
055  * @param model a BioPAX model
056  * @param outputStream output stream
057  */
058 void convertToOWL(Model model, OutputStream outputStream);
059
060 /**
061  * This flag will allow reader to automatically convert level1 classes to
062  * corresponding level 2 classes.
063  * @param convertingFromLevel1ToLevel2 true/false, whether actual BioPAX data is of Level1
064  * @deprecated BioPAX Level 1 exports are obsolete (anyway, L1 input is always converted to L2 automatically).
065  */
066 void setConvertingFromLevel1ToLevel2(boolean convertingFromLevel1ToLevel2);
067
068 /**
069  * This flag will fix a common legacy bug from BioCyc where the "NIL" string
070  * was used for representing unknown values.
071  * @return true if this option is enabled.
072  */
073 boolean isTreatNilAsNull();
074
075 /**
076  * This flag will allow reader to automatically convert level1 classes to
077  * corresponding level 2 classes.
078  * @return true if this option is enabled (e.g. auto-enabled if Level1 data were detected).
079  */
080 boolean isConvertingFromLevel1ToLevel2();
081
082 /**
083  * This option is only applicable two level 2 models.
084  * When enabled it will replicate illegally reused
085  * pysicalEntityParticipants in Level2 files.
086  * @return true if this option is enabled.
087  */
088 boolean isFixReusedPEPs();
089
090 /**
091  * @return the factory that is used to create new BioPAX POJOs during a BioPAXIOHandler operation.
092  */
093 BioPAXFactory getFactory();
094
095 /**
096  * @param factory used for creating objects
097  */
098 void setFactory(BioPAXFactory factory);
099
100 /**
101  * @return EditorMap used for this handler.
102  */
103 EditorMap getEditorMap();
104
105 /**
106  * @param editorMap used for this handler.
107  */
108 void setEditorMap(EditorMap editorMap);
109
110 /**
111  * @return The level of the model that is being read.
112  */
113 BioPAXLevel getLevel();
114
115 /**
116  * This method will "excise" a new model from the given model that contains
117  * the objects with given ids and their dependents.
118  * @param model BioPAX object model to be exported to the output stream as RDF/XML
119  * @param outputStream the stream
120  * @param ids optional list of absolute URIs of BioPAX objects - roots/seeds for extracting a sub-model to be exported
121  */
122 void convertToOWL(Model model, OutputStream outputStream, String... ids);
123}