01: /*
02: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
03: *
04: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
05: *
06: * The contents of this file are subject to the terms of either the GNU
07: * General Public License Version 2 only ("GPL") or the Common
08: * Development and Distribution License("CDDL") (collectively, the
09: * "License"). You may not use this file except in compliance with the
10: * License. You can obtain a copy of the License at
11: * http://www.netbeans.org/cddl-gplv2.html
12: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
13: * specific language governing permissions and limitations under the
14: * License. When distributing the software, include this License Header
15: * Notice in each file and include the License file at
16: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
17: * particular file as subject to the "Classpath" exception as provided
18: * by Sun in the GPL Version 2 section of the License file that
19: * accompanied this code. If applicable, add the following below the
20: * License Header, with the fields enclosed by brackets [] replaced by
21: * your own identifying information:
22: * "Portions Copyrighted [year] [name of copyright owner]"
23: *
24: * Contributor(s):
25: *
26: * The Original Software is NetBeans. The Initial Developer of the Original
27: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
28: * Microsystems, Inc. All Rights Reserved.
29: *
30: * If you wish your version of this file to be governed by only the CDDL
31: * or only the GPL Version 2, indicate your decision by adding
32: * "[Contributor] elects to include this software in this distribution
33: * under the [CDDL or GPL Version 2] license." If you do not indicate a
34: * single choice of license, a recipient has the option to distribute
35: * your version of this file under either the CDDL, the GPL Version 2 or
36: * to extend the choice of license to its licensees as provided above.
37: * However, if you add GPL Version 2 code and therefore, elected the GPL
38: * Version 2 license, then the option applies only if the new code is
39: * made subject to such option by the copyright holder.
40: */
41:
42: package org.netbeans.spi.queries;
43:
44: import java.io.File;
45:
46: /**
47: * A query which should typically be provided by a VCS to give information
48: * about whether some files can be considered part of one logical directory tree.
49: * <p>
50: * This should be treated as a heuristic, useful when deciding whether to use
51: * absolute or relative links between path locations.
52: * </p>
53: * <p>
54: * The file names might refer to nonexistent files. A provider may or may not
55: * be able to say anything useful about them in this case.
56: * </p>
57: * <p>
58: * File names passed to this query will already have been normalized according to
59: * the semantics of {@link org.openide.filesystems.FileUtil#normalizeFile}.
60: * </p>
61: * <p>
62: * Threading note: implementors should avoid acquiring locks that might be held
63: * by other threads. Generally treat this interface similarly to SPIs in
64: * {@link org.openide.filesystems} with respect to threading semantics.
65: * </p>
66: * @see org.netbeans.api.queries.CollocationQuery
67: * @author Jesse Glick
68: */
69: public interface CollocationQueryImplementation {
70:
71: /**
72: * Check whether two files are logically part of one directory tree.
73: * For example, if both files are stored in CVS, with the same server
74: * (<code>CVSROOT</code>) they might be considered collocated.
75: * If they are to be collocated their absolute paths must share a
76: * prefix directory, i.e. they must be located in the same filesystem root.
77: * If nothing is known about them, return false.
78: * @param file1 one file
79: * @param file2 another file
80: * @return true if they are probably part of one logical tree
81: */
82: boolean areCollocated(File file1, File file2);
83:
84: /**
85: * Find a root of a logical tree containing this file, if any.
86: * The path of the root (if there is one) must be a prefix of the path of the file.
87: * @param file a file on disk (must be an absolute URI)
88: * @return an ancestor directory which is the root of a logical tree,
89: * if any (else null) (must be an absolute URI)
90: */
91: File findRoot(File file);
92:
93: }
|