tikhomirov@355: /*
tikhomirov@355:  * Copyright (c) 2011 TMate Software Ltd
tikhomirov@355:  *  
tikhomirov@355:  * This program is free software; you can redistribute it and/or modify
tikhomirov@355:  * it under the terms of the GNU General Public License as published by
tikhomirov@355:  * the Free Software Foundation; version 2 of the License.
tikhomirov@355:  *
tikhomirov@355:  * This program is distributed in the hope that it will be useful,
tikhomirov@355:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
tikhomirov@355:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
tikhomirov@355:  * GNU General Public License for more details.
tikhomirov@355:  *
tikhomirov@355:  * For information on how to redistribute this software under
tikhomirov@355:  * the terms of a license other than GNU General Public License
tikhomirov@355:  * contact TMate Software at support@hg4j.com
tikhomirov@355:  */
tikhomirov@355: package org.tmatesoft.hg.internal;
tikhomirov@355: 
tikhomirov@355: import java.nio.ByteBuffer;
tikhomirov@355: import java.nio.channels.ByteChannel;
tikhomirov@355: 
tikhomirov@355: /**
tikhomirov@355:  * Filters may need to look into data stream before actual processing takes place,
tikhomirov@355:  * for example, to find out whether filter shall be applied at all.
tikhomirov@355:  * 
tikhomirov@355:  * {@link ByteChannel ByteChannels} that may use filters shall be checked for {@link Preview} adaptable before writing to them. 
tikhomirov@355:  * 
tikhomirov@355:  * E.g. newline filter handles streams with mixed newline endings according to configuration option 
tikhomirov@355:  * (either process or ignore), hence, need to check complete stream first.
tikhomirov@355:  * 
tikhomirov@355:  * @author Artem Tikhomirov
tikhomirov@355:  * @author TMate Software Ltd.
tikhomirov@355:  */
tikhomirov@355: public interface Preview {
tikhomirov@355: 	/**
tikhomirov@355: 	 * Supplied buffer may be shared between few Preview filter instances, hence implementers shall NOT consume (move position)
tikhomirov@355: 	 * of the buffer. Caller enforces this reseting buffer position between calls to previewers.
tikhomirov@355: 	 * <p>
tikhomirov@355: 	 * XXX if this approach turns out to impose a great burden on filter implementations, FilterByteChannel may be modified to keep
tikhomirov@355: 	 * record of how far each filter had read it's buffer. 
tikhomirov@355: 	 */
tikhomirov@355: 	void preview(ByteBuffer src);
tikhomirov@355: }