1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.configuration2.io; 18 19 import java.io.IOException; 20 import java.io.Reader; 21 import java.io.Writer; 22 23 import org.apache.commons.configuration2.ex.ConfigurationException; 24 25 /** 26 * <p> 27 * Definition of an interface to be implemented by objects which know how to read and write themselves from or to a 28 * character stream. 29 * </p> 30 * <p> 31 * This interface is implemented by special implementations of the {@code Configuration} interface which are associated 32 * with a file. It demands only basic methods for doing I/O based on character stream objects. Based on these methods it 33 * is possible to implement other methods which operate on files, file names, URLs, etc. 34 * </p> 35 * <p> 36 * <strong>Note that the methods defined by this interface are not intended to be called directly by client 37 * code!</strong> Rather, they are used internally when doing I/O operations with a {@link FileHandler}. A 38 * {@code FileHandler} supports additional functionality (e.g. it evaluates some additional interfaces the 39 * {@code FileBased} object may implement); this functionality is not available on a direct method invocation, so this 40 * may lead to unpredictable results. 41 * </p> 42 */ 43 public interface FileBased { 44 /** 45 * Reads the content of this object from the given reader. <strong>Client code should not call this method directly, but 46 * use a {@code FileHandler} for reading data.</strong> 47 * 48 * @param in the reader 49 * @throws IOException if an I/O error occurs. 50 * @throws ConfigurationException if a non-I/O related problem occurs, e.g. the data read does not have the expected 51 * format 52 */ 53 void read(Reader in) throws ConfigurationException, IOException; 54 55 /** 56 * Writes the content of this object to the given writer. <strong>Client code should not call this method directly, but 57 * use a {@code FileHandler} for writing data.</strong> 58 * 59 * @param out the writer 60 * @throws IOException if an I/O error occurs. 61 * @throws ConfigurationException if a non-I/O related problem occurs, e.g. the data read does not have the expected 62 * format 63 */ 64 void write(Writer out) throws ConfigurationException, IOException; 65 }