Mercurial > hg4j

annotate src/org/tmatesoft/hg/util/FileIterator.java @ 434:7e1912b4ce99 v0.9.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Record few known issues while skimming through TODOs
author Artem Tikhomirov <tikhomirov.artem@gmail.com>
date Fri, 30 Mar 2012 17:11:39 +0200
parents 7f27122011c3
children b3b1db9301a2
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
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
21 import org.tmatesoft.hg.internal.Experimental;
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
22
141
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
23 /**
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
24 * 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
25 *
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
26 * @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
27 * @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
28 */
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
29 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
30
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 * 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
33 */
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
34 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
35
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 * @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
38 */
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
39 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
40
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 * 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
43 */
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
44 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
45
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 * @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
48 */
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
49 Path name();
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
50
8248aae33f7d Adopt FileIterator moving towards WCStatusCollector parameterizing. Improved path handling, move 'em around
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents:
diff changeset
51 /**
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
52 * {@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
53 * 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
54 * @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
55 */
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
56 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
57
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 * 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
60 * 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
61 * 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
62 * asked.
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 * @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
64 */
26ad7827a62d Support status query for a single file or a subdirectory of a repository
Artem Tikhomirov <tikhomirov.artem@gmail.com>
parents: 141
diff changeset
65 @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")
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
66 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
67
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
68 /**
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
69 * 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
70 * 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
71 * @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
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 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
74
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 /**
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 * 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
77 * 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
78 * 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
79 * @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
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 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
82 }