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@444: import org.tmatesoft.hg.repo.HgStatusCollector;
tikhomirov@444: import org.tmatesoft.hg.repo.HgWorkingCopyStatusCollector;
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@444: 	 * <p>
tikhomirov@444: 	 * Implementors are advised to use {@link Path.Matcher}, as this scope is very similar to what regular 
tikhomirov@444: 	 * {@link HgStatusCollector} (which doesn't use FI) supports, and use of matcher makes {@link HgWorkingCopyStatusCollector}
tikhomirov@444: 	 * look similar.
tikhomirov@444: 	 * 
tikhomirov@226: 	 * @return <code>true</code> if this {@link FileIterator} is responsible for (interested in) specified repository-local path 
tikhomirov@226: 	 */
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: }