tikhomirov@141: /*
tikhomirov@413:  * Copyright (c) 2011-2012 TMate Software Ltd
tikhomirov@141:  *  
tikhomirov@141:  * This program is free software; you can redistribute it and/or modify
tikhomirov@141:  * it under the terms of the GNU General Public License as published by
tikhomirov@141:  * the Free Software Foundation; version 2 of the License.
tikhomirov@141:  *
tikhomirov@141:  * This program is distributed in the hope that it will be useful,
tikhomirov@141:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
tikhomirov@141:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
tikhomirov@141:  * GNU General Public License for more details.
tikhomirov@141:  *
tikhomirov@141:  * For information on how to redistribute this software under
tikhomirov@141:  * the terms of a license other than GNU General Public License
tikhomirov@141:  * contact TMate Software at support@hg4j.com
tikhomirov@141:  */
tikhomirov@141: package org.tmatesoft.hg.util;
tikhomirov@141: 
tikhomirov@350: import java.io.IOException;
tikhomirov@350: 
tikhomirov@226: import org.tmatesoft.hg.internal.Experimental;
tikhomirov@226: 
tikhomirov@141: /**
tikhomirov@141:  * Abstracts iteration over file system.
tikhomirov@141:  * 
tikhomirov@141:  * @author Artem Tikhomirov
tikhomirov@141:  * @author TMate Software Ltd.
tikhomirov@141:  */
tikhomirov@141: public interface FileIterator {
tikhomirov@141: 
tikhomirov@141: 	/**
tikhomirov@141: 	 * Brings iterator into initial state to facilitate new use.
tikhomirov@141: 	 */
tikhomirov@350: 	void reset() throws IOException;
tikhomirov@141: 
tikhomirov@141: 	/**
tikhomirov@141: 	 * @return whether can shift to next element
tikhomirov@141: 	 */
tikhomirov@350: 	boolean hasNext() throws IOException;
tikhomirov@141: 
tikhomirov@141: 	/**
tikhomirov@141: 	 * Shift to next element
tikhomirov@141: 	 */
tikhomirov@350: 	void next() throws IOException;
tikhomirov@141: 
tikhomirov@141: 	/**
tikhomirov@141: 	 * @return repository-local path to the current element.
tikhomirov@141: 	 */
tikhomirov@141: 	Path name();
tikhomirov@141: 
tikhomirov@141: 	/**
tikhomirov@287: 	 * {@link FileInfo} object to retrieve actual file information. Caller shall not assume new instance for each {@link #next()} entry, 
tikhomirov@287: 	 * implementors of this interface may reuse {@link FileInfo} instance if deemed suitable. 
tikhomirov@287: 	 * @return file information holder.
tikhomirov@141: 	 */
tikhomirov@287: 	FileInfo file();
tikhomirov@226: 
tikhomirov@226: 	/**
tikhomirov@226: 	 * When {@link FileIterator} represents only fraction of a repository, library might need to figure out if
tikhomirov@287: 	 * specific file (path) belongs to that fraction or not. Paths and files returned by this {@link FileIterator}
tikhomirov@226: 	 * are always considered as representing the fraction, nonetheless, {@link FileIterator} shall return true for such names if 
tikhomirov@226: 	 * asked.
tikhomirov@226: 	 * @return <code>true</code> if this {@link FileIterator} is responsible for (interested in) specified repository-local path 
tikhomirov@226: 	 */
tikhomirov@226: 	@Experimental(reason="Perhaps, shall not be part of FileIterator, but rather separate Path.Matcher. Approaches in regular StatusCollector (doesn't use FI, but supports scope) and WC collector to look similar, and for HgStatusCommand to use single approach to set the scope")
tikhomirov@413: 	boolean inScope(Path file); // PathMatcher scope()
tikhomirov@413: 
tikhomirov@413: 	/**
tikhomirov@413: 	 * Tells whether caller shall be aware of distinction between executable and non-executable files coming from this iterator.
tikhomirov@413: 	 * Note, these days Mercurial (as of 2.1) doesn't recognize Windows .exe files as executable (nor it treats any Windows filesystem as exec-capable) 
tikhomirov@413: 	 * @return <code>true</code> if file descriptors are capable to provide executable flag
tikhomirov@413: 	 */
tikhomirov@413: 	boolean supportsExecFlag();
tikhomirov@413: 
tikhomirov@413: 	/**
tikhomirov@413: 	 * POSIX file systems allow symbolic links to files, and these links are handled in a special way with Mercurial, i.e. it tracks value of 
tikhomirov@413: 	 * the link, not its actual target.
tikhomirov@413: 	 * Note, these days Mercurial (as of 2.1) doesn't support Windows Vista/7 symlinks.
tikhomirov@413: 	 * @return <code>true</code> if file descriptors are capable to tell symlink files from regular ones. 
tikhomirov@413: 	 */
tikhomirov@413: 	boolean supportsLinkFlag();
tikhomirov@141: }