SourceForBinaryQueryImplementation


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.netbeans.spi.java.queries;
20  
21  import java.net.URL  ;
22  import org.netbeans.api.java.queries.SourceForBinaryQuery;
23  import org.openide.filesystems.FileObject;
24  
25  // XXX add a listener to changes in result
26  
27  /**
28   * Information about where Java sources corresponding to binaries
29   * (classfiles) can be found.
30   * <p>
31   * A default implementation is registered by the
32   * <code>org.netbeans.modules.java.project</code> module which looks up the
33   * project corresponding to the file (if any; <code>jar</code>-protocol URLs
34   * actually check the owner of the JAR file itself) and checks whether that
35   * project has an implementation of this interface in its lookup. If so, it
36   * delegates to that implementation. Therefore it is not generally necessary
37   * for a project type provider to register its own global implementation of
38   * this query, if it depends on the Java Project module and uses this style.
39   * </p>
40   * <div class="nonnormative">
41   * <p>
42   * Note that if you supply a <code>SourceForBinaryQueryImplementation</code>
43   * corresponding to an entry in a {@link org.netbeans.spi.java.classpath.ClassPathProvider} for some source
44   * files, there needs to be a {@link org.netbeans.spi.java.classpath.ClassPathProvider} for the sources
45   * used as dependencies as well. Otherwise code completion will not work well;
46   * the current parser database creation strategy uses the following search order
47   * when deciding what to parse for a binary classpath element:
48   * </p>
49   * <ol>
50   * <li>The sources returned by <code>SourceForBinaryQueryImplementation</code>,
51   *     <em>if</em> these have at least a bootclasspath specified as well by some
52   *     {@link org.netbeans.spi.java.classpath.ClassPathProvider}.</li>
53   * <li>Compiled classes mixed into the "source" directory, if there are any.</li>
54   * <li>Compiled classes in the binary classpath element.</li>
55   * </ol>
56   * </div>
57   * @see org.netbeans.api.java.queries.SourceForBinaryQuery
58   * @see org.netbeans.api.queries.FileOwnerQuery
59   * @see org.netbeans.api.project.Project#getLookup
60   * @since org.netbeans.api.java/1 1.4
61   */
62  public interface SourceForBinaryQueryImplementation {
63  
64      /**
65       * Returns the source root(s) for a given binary root.
66       * <p>
67       * The returned SourceForBinaryQuery.Result must be a singleton. It means that for
68       * repeated calling of this method with the same recognized root the method has to
69       * return the same instance of SourceForBinaryQuery.Result.<br>
70       * The typical implemantation of the findSourceRoots contains 3 steps:
71       * <ol>
72       * <li>Look into the cache if there is already a result for the root, if so return it</li>
73       * <li>Check if the binaryRoot is recognized, if not return null</li>
74       * <li>Create a new SourceForBinaryQuery.Result for the binaryRoot, put it into the cache
75       * and return it.</li>
76       * </ol>
77       * </p>
78       * <p>
79       * Any absolute URL may be used but typically it will use the <code>file</code>
80       * protocol for directory entries and <code>jar</code> protocol for JAR entries
81       * (e.g. <samp>jar:file:/tmp/foo.jar!/</samp>).
82       * </p>
83       * @param binaryRoot the class path root of Java class files
84       * @return a result object encapsulating the answer or null if the binaryRoot is not recognized
85       */
86      public SourceForBinaryQuery.Result findSourceRoots(URL   binaryRoot);
87      
88  }
89
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags