Mercurial > jhg

annotate src/org/tmatesoft/hg/util/FileIterator.java @ 493:ba36f66c32b4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Refactor to keep knowledge about repository control files and their location in respect to .hg/ in a single place (facilitate future adoption of shared repositories)
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Thu, 18 Oct 2012 18:36:13 +0200
parents b3b1db9301a2
children
rev   line source
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
1 /*
413
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
2 * Copyright (c) 2011-2012 TMate Software Ltd
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
3 *
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
4 * This program is free software; you can redistribute it and/or modify
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
5 * it under the terms of the GNU General Public License as published by
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
6 * the Free Software Foundation; version 2 of the License.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
7 *
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
8 * This program is distributed in the hope that it will be useful,
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
11 * GNU General Public License for more details.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
12 *
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
13 * For information on how to redistribute this software under
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
14 * the terms of a license other than GNU General Public License
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
15 * contact TMate Software at support@hg4j.com
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
16 */
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
17 package org.tmatesoft.hg.util;
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
18
350
33eaed1ad130 Allow FileIterator report any errors from the underlaying file system up to the client
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 287
diff changeset
19 import java.io.IOException;
33eaed1ad130 Allow FileIterator report any errors from the underlaying file system up to the client
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 287
diff changeset
20
444
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
21 import org.tmatesoft.hg.repo.HgStatusCollector;
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
22 import org.tmatesoft.hg.repo.HgWorkingCopyStatusCollector;
226
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
23
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
24 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
25 * Abstracts iteration over file system.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
26 *
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
27 * @author Artem Tikhomirov
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
28 * @author TMate Software Ltd.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
29 */
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
30 public interface FileIterator {
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
31
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
32 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
33 * Brings iterator into initial state to facilitate new use.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
34 */
350
33eaed1ad130 Allow FileIterator report any errors from the underlaying file system up to the client
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 287
diff changeset
35 void reset() throws IOException;
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
36
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
37 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
38 * @return whether can shift to next element
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
39 */
350
33eaed1ad130 Allow FileIterator report any errors from the underlaying file system up to the client
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 287
diff changeset
40 boolean hasNext() throws IOException;
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
41
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
42 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
43 * Shift to next element
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
44 */
350
33eaed1ad130 Allow FileIterator report any errors from the underlaying file system up to the client
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 287
diff changeset
45 void next() throws IOException;
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
46
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
47 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
48 * @return repository-local path to the current element.
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
49 */
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
50 Path name();
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
51
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
52 /**
287
ed6b74a58c66 Use FileInfo abstraction with necessary subset of File functionality instead of File to facilitate other effective file system iterators
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 226
diff changeset
53 * {@link FileInfo} object to retrieve actual file information. Caller shall not assume new instance for each {@link #next()} entry,
ed6b74a58c66 Use FileInfo abstraction with necessary subset of File functionality instead of File to facilitate other effective file system iterators
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 226
diff changeset
54 * implementors of this interface may reuse {@link FileInfo} instance if deemed suitable.
ed6b74a58c66 Use FileInfo abstraction with necessary subset of File functionality instead of File to facilitate other effective file system iterators
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 226
diff changeset
55 * @return file information holder.
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
56 */
287
ed6b74a58c66 Use FileInfo abstraction with necessary subset of File functionality instead of File to facilitate other effective file system iterators
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 226
diff changeset
57 FileInfo file();
226
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
58
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
59 /**
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
60 * When {@link FileIterator} represents only fraction of a repository, library might need to figure out if
287
ed6b74a58c66 Use FileInfo abstraction with necessary subset of File functionality instead of File to facilitate other effective file system iterators
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 226
diff changeset
61 * specific file (path) belongs to that fraction or not. Paths and files returned by this {@link FileIterator}
226
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
62 * are always considered as representing the fraction, nonetheless, {@link FileIterator} shall return true for such names if
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
63 * asked.
444
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
64 * <p>
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
65 * Implementors are advised to use {@link Path.Matcher}, as this scope is very similar to what regular
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
66 * {@link HgStatusCollector} (which doesn't use FI) supports, and use of matcher makes {@link HgWorkingCopyStatusCollector}
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
67 * look similar.
b3b1db9301a2 Few comments that emerged while working on examples
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 413
diff changeset
68 *
226
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
69 * @return <code>true</code> if this {@link FileIterator} is responsible for (interested in) specified repository-local path
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
70 */
413
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
71 boolean inScope(Path file); // PathMatcher scope()
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
72
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
73 /**
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
74 * Tells whether caller shall be aware of distinction between executable and non-executable files coming from this iterator.
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
75 * 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)
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
76 * @return <code>true</code> if file descriptors are capable to provide executable flag
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
77 */
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
78 boolean supportsExecFlag();
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
79
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
80 /**
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
81 * 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
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
82 * the link, not its actual target.
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
83 * Note, these days Mercurial (as of 2.1) doesn't support Windows Vista/7 symlinks.
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
84 * @return <code>true</code> if file descriptors are capable to tell symlink files from regular ones.
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
85 */
7f27122011c3 Support and respect for symbolic links and executable flag, with /bin/ls backed implementation to discover these
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 350
diff changeset
86 boolean supportsLinkFlag();
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
87 }