Mercurial > hg4j

annotate src/org/tmatesoft/hg/util/FileIterator.java @ 444:b3b1db9301a2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Few comments that emerged while working on examples
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Tue, 15 May 2012 20:19:22 +0200
parents 7f27122011c3
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 }