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 <egonw@users.sf.net> 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