001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.netbeans.modules.gsfpath.spi.queries;
042:
043: import java.net.URL;
044: import org.netbeans.modules.gsfpath.api.queries.SourceForBinaryQuery;
045: import org.openide.filesystems.FileObject;
046:
047: // XXX add a listener to changes in result
048:
049: /**
050: * Information about where Java sources corresponding to binaries
051: * (classfiles) can be found.
052: * <p>
053: * A default implementation is registered by the
054: * <code>org.netbeans.modules.gsfpath.project</code> module which looks up the
055: * project corresponding to the file (if any; <code>jar</code>-protocol URLs
056: * actually check the owner of the JAR file itself) and checks whether that
057: * project has an implementation of this interface in its lookup. If so, it
058: * delegates to that implementation. Therefore it is not generally necessary
059: * for a project type provider to register its own global implementation of
060: * this query, if it depends on the Java Project module and uses this style.
061: * </p>
062: * <div class="nonnormative">
063: * <p>
064: * Note that if you supply a <code>SourceForBinaryQueryImplementation</code>
065: * corresponding to an entry in a {@link org.netbeans.modules.gsfpath.spi.classpath.ClassPathProvider} for some source
066: * files, there needs to be a {@link org.netbeans.modules.gsfpath.spi.classpath.ClassPathProvider} for the sources
067: * used as dependencies as well. Otherwise code completion will not work well;
068: * the current parser database creation strategy uses the following search order
069: * when deciding what to parse for a binary classpath element:
070: * </p>
071: * <ol>
072: * <li>The sources returned by <code>SourceForBinaryQueryImplementation</code>,
073: * <em>if</em> these have at least a bootclasspath specified as well by some
074: * {@link org.netbeans.modules.gsfpath.spi.classpath.ClassPathProvider}.</li>
075: * <li>Compiled classes mixed into the "source" directory, if there are any.</li>
076: * <li>Compiled classes in the binary classpath element.</li>
077: * </ol>
078: * </div>
079: * @see org.netbeans.modules.gsfpath.api.queries.SourceForBinaryQuery
080: * @see org.netbeans.api.queries.FileOwnerQuery
081: * @see org.netbeans.api.project.Project#getLookup
082: * @since org.netbeans.modules.gsfpath.api/1 1.4
083: */
084: public interface SourceForBinaryQueryImplementation {
085:
086: /**
087: * Returns the source root(s) for a given binary root.
088: * <p>
089: * The returned SourceForBinaryQuery.Result must be a singleton. It means that for
090: * repeated calling of this method with the same recognized root the method has to
091: * return the same instance of SourceForBinaryQuery.Result.<br>
092: * The typical implemantation of the findSourceRoots contains 3 steps:
093: * <ol>
094: * <li>Look into the cache if there is already a result for the root, if so return it</li>
095: * <li>Check if the binaryRoot is recognized, if not return null</li>
096: * <li>Create a new SourceForBinaryQuery.Result for the binaryRoot, put it into the cache
097: * and return it.</li>
098: * </ol>
099: * </p>
100: * <p>
101: * Any absolute URL may be used but typically it will use the <code>file</code>
102: * protocol for directory entries and <code>jar</code> protocol for JAR entries
103: * (e.g. <samp>jar:file:/tmp/foo.jar!/</samp>).
104: * </p>
105: * @param binaryRoot the class path root of Java class files
106: * @return a result object encapsulating the answer or null if the binaryRoot is not recognized
107: */
108: public SourceForBinaryQuery.Result findSourceRoots(URL binaryRoot);
109:
110: }
|