1 /* Copyright (C) 2000-2007,2010  Egon Willighagen <egonw@users.sf.net>
2  *
3  * Contact: cdk-devel@lists.sourceforge.net
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public License
7  * as published by the Free Software Foundation; either version 2.1
8  * of the License, or (at your option) any later version.
9  * All we ask is that proper credit is given for our work, which includes
10  * - but is not limited to - adding the above copyright notice to the beginning
11  * of your source code files, and to any copyright notice that you may distribute
12  * with programs based on this work.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this program; if not, write to the Free Software
21  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
22  */
23 package org.openscience.cdk.io;
24 
25 import java.io.InputStream;
26 import java.io.Reader;
27 
28 import org.openscience.cdk.exception.CDKException;
29 import org.openscience.cdk.io.iterator.IIteratingChemObjectReader;
30 
31 /**
32  * This interface specifies the common functionality all IO readers should provide.
33  *
34  * IO readers should not implement this interface directly, but rather implement
35  * one of its child interfaces: {@link ISimpleChemObjectReader} or {@link IIteratingChemObjectReader}.
36  * These sub-interfaces specify the information access methods:
37  * a simple read() method for the {@link ISimpleChemObjectReader} and
38  * more advanced iterator based access for the {@link IIteratingChemObjectReader} (suitable for large files)
39  *
40  * @cdk.module io
41  * @cdk.githash
42  *
43  * @author Egon Willighagen &lt;egonw@users.sf.net&gt;
44  * @see ISimpleChemObjectReader
45  * @see IIteratingChemObjectReader
46  **/
47 public interface IChemObjectReader extends IChemObjectIO {
48 
49     public enum Mode {
50         /** Only fail on serious format problems */
51         RELAXED,
52         /** Fail on any format problem */
53         STRICT
54     }
55 
56     /**
57      * Sets the Reader from which this ChemObjectReader should read
58      * the contents.
59      */
setReader(Reader reader)60     public void setReader(Reader reader) throws CDKException;
61 
62     /**
63      * Sets the InputStream from which this ChemObjectReader should read
64      * the contents.
65      */
setReader(InputStream reader)66     public void setReader(InputStream reader) throws CDKException;
67 
68     /**
69      * Sets the reader mode. If Mode.STRICT, then the reader will fail on
70      * any problem in the format of the read file, instead of trying to
71      * recover from that.
72      *
73      * @param mode
74      */
setReaderMode(Mode mode)75     public void setReaderMode(Mode mode);
76 
77     /**
78      * Sets an error handler that is sent events when file format issues occur.
79      *
80      * @param handler {@link IChemObjectReaderErrorHandler} to send error
81      *                messages to.
82      */
setErrorHandler(IChemObjectReaderErrorHandler handler)83     public void setErrorHandler(IChemObjectReaderErrorHandler handler);
84 
85     /**
86      * Redirects an error message to the {@link IChemObjectReaderErrorHandler}.
87      * Throws an {@link CDKException} when in STRICT {@link Mode}.
88      *
89      * @param message the error message.
90      */
handleError(String message)91     public void handleError(String message) throws CDKException;
92 
93     /**
94      * Redirects an error message to the {@link IChemObjectReaderErrorHandler}.
95      * Throws an {@link CDKException} when in STRICT {@link Mode}.
96      *
97      * @param message  the error message.
98      * @param exception the corresponding {@link Exception}.
99      */
handleError(String message, Exception exception)100     public void handleError(String message, Exception exception) throws CDKException;
101 
102     /**
103      * Redirects an error message to the {@link IChemObjectReaderErrorHandler}.
104      * Throws an {@link CDKException} when in STRICT {@link Mode}.
105      *
106      * @param message  the error message.
107      * @param row      Row in the file where the error is found.
108      * @param colStart Start column in the file where the error is found.
109      * @param colEnd   End column in the file where the error is found.
110      */
handleError(String message, int row, int colStart, int colEnd)111     public void handleError(String message, int row, int colStart, int colEnd) throws CDKException;
112 
113     /**
114      * Redirects an error message to the {@link IChemObjectReaderErrorHandler}.
115      * Throws an {@link CDKException} when in STRICT {@link Mode}.
116      *
117      * @param message  the error message.
118      * @param exception the corresponding {@link Exception}.
119      * @param row       Row in the file where the error is found.
120      * @param colStart Start column in the file where the error is found.
121      * @param colEnd   End column in the file where the error is found.
122      */
handleError(String message, int row, int colStart, int colEnd, Exception exception)123     public void handleError(String message, int row, int colStart, int colEnd, Exception exception) throws CDKException;
124 }
125