ide/csl.api/doc/classpath.html - netbeans - Git at Google

 <!--

     Licensed to the Apache Software Foundation (ASF) under one
     or more contributor license agreements.  See the NOTICE file
     distributed with this work for additional information
     regarding copyright ownership.  The ASF licenses this file
     to you under the Apache License, Version 2.0 (the
     "License"); you may not use this file except in compliance
     with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.

 -->
 <html>
     <body>
         <h3>GSF Classpath</h3>
         <p>
             <blockquote style="background-color: #ffdddd; color: black; padding: 20px; border: solid 1px black">
                 WARNING: GSF has its own Classpath copy of the Java one, slightly renamed
                 and in a different package. However, in NetBeans 6.5, the Java Classpath
                 module has been moved from the java cluster into the IDE cluster and should
                 be generic. I plan to retrofit GSF to use the standard Classpath package
                 as soon as possible.
             </blockquote>
             <blockquote style="background-color: #ffdddd; color: black; padding: 20px; border: solid 1px black">
                 NOTE 2: The class path and project integration aspects of GSF are really half baked
                 at this point. It works, but it's not pretty, and this is an area that I <b>know</b>
                 will need to change and I plan to do something about it.
             </blockquote>
         </p>
         <p>
             The GSF classpath API sits in its own module and its own package: <code>gsfpath.api</code>.
             It's a pretty small API. All it boils down to this this:  For each project type
             (Ruby Project, Web Project for JavaScript, Groovy project for Groovy, etc.) you have
             to tell GSF where your sources are. The way you do this is to register a
             "project open hook", a callback provided by the project system which will call custom
             code after the project is opened.  In the project open hook, you register a series
             of directories with GSF. That's really the gist of it.
         </p>
         <p>
             Unfortunately, it's not the 3 lines it sounds like. What you actually have to register
             are "Classpath" objects, one for each source root, and one for each library.
             A classpath has both a directory/url, as well as a "type", such as "SOURCE" or "BOOT".
             A "SOURCE" classpath is exactly what you expect - it's a root directory for sources
             in your project. "BOOT" on the other hand designates a library. As explained in the
             <a href="indexer.html">indexing</a> document, these can be treated differently by
             the code. Some features may only want to search local project sources, and so on.
         </p>
         <p>
             What you end up doing is something like the following (I will use the Rails project
             as an example):
             <ol>
                 <li>Implement an implementation of a ClasspathProvider
                     (org.netbeans.modules.gsfpath.spi.classpath.ClassPathProvider).
                     In the Rails case, this is the ClassPathProviderImpl class in ruby.railsproject.
                     I will describe this class in more detail below.
                 </li>
                 <li> Register the ClassPathProviderImpl in your project's lookup.
                 <li> In your project's <code>open</code> hook, register your class path
                     with the global path registry, like this:
                     <pre>
     ClassPathProviderImpl cpProvider = getLookup().lookup(ClassPathProviderImpl.class);
     GlobalPathRegistry.getDefault().register(ClassPath.BOOT, cpProvider.getProjectClassPaths(ClassPath.BOOT));
     GlobalPathRegistry.getDefault().register(ClassPath.SOURCE, cpProvider.getProjectClassPaths(ClassPath.SOURCE));
                     </pre>
                 </li>
                 <li>
                     Similarly. in your project's <code>close</code> hook, unregister the paths:
                     <pre>
     ClassPathProviderImpl cpProvider = getLookup().lookup(ClassPathProviderImpl.class);
     GlobalPathRegistry.getDefault().unregister(ClassPath.BOOT, cpProvider.getProjectClassPaths(ClassPath.BOOT));
     GlobalPathRegistry.getDefault().unregister(ClassPath.SOURCE, cpProvider.getProjectClassPaths(ClassPath.SOURCE));
                     </pre>
                 </li>
             </ol>

             That's basically it. So the only trick here is implementing the <code>ClasspathProvider</code>.
             Take a look at the one in the Rails project, or the Web project (<code>web.project</code>), etc.
             It's not rocket science. You just have to do whatever it takes for the specific project type
             to look up the source roots, decide whether all of these are relevant for your file type
             (for example, in Web projects, I only register the web folder for JavaScript, not the src folder
             which just contains Java code) and then produce classpath implementation objects for these.
             There are utility methods to help.
         </p>
         <p>
             As I warned in the red box above, this will probably change soon.
         </p>
     </body>
 </html>
	<!--

	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	-->
	<html>
	<body>
	<h3>GSF Classpath</h3>
	<p>
	<blockquote style="background-color: #ffdddd; color: black; padding: 20px; border: solid 1px black">
	WARNING: GSF has its own Classpath copy of the Java one, slightly renamed
	and in a different package. However, in NetBeans 6.5, the Java Classpath
	module has been moved from the java cluster into the IDE cluster and should
	be generic. I plan to retrofit GSF to use the standard Classpath package
	as soon as possible.
	</blockquote>
	<blockquote style="background-color: #ffdddd; color: black; padding: 20px; border: solid 1px black">
	NOTE 2: The class path and project integration aspects of GSF are really half baked
	at this point. It works, but it's not pretty, and this is an area that I <b>know</b>
	will need to change and I plan to do something about it.
	</blockquote>
	</p>
	<p>
	The GSF classpath API sits in its own module and its own package: <code>gsfpath.api</code>.
	It's a pretty small API. All it boils down to this this: For each project type
	(Ruby Project, Web Project for JavaScript, Groovy project for Groovy, etc.) you have
	to tell GSF where your sources are. The way you do this is to register a
	"project open hook", a callback provided by the project system which will call custom
	code after the project is opened. In the project open hook, you register a series
	of directories with GSF. That's really the gist of it.
	</p>
	<p>
	Unfortunately, it's not the 3 lines it sounds like. What you actually have to register
	are "Classpath" objects, one for each source root, and one for each library.
	A classpath has both a directory/url, as well as a "type", such as "SOURCE" or "BOOT".
	A "SOURCE" classpath is exactly what you expect - it's a root directory for sources
	in your project. "BOOT" on the other hand designates a library. As explained in the
	<a href="indexer.html">indexing</a> document, these can be treated differently by
	the code. Some features may only want to search local project sources, and so on.
	</p>
	<p>
	What you end up doing is something like the following (I will use the Rails project
	as an example):
	<ol>
	<li>Implement an implementation of a ClasspathProvider
	(org.netbeans.modules.gsfpath.spi.classpath.ClassPathProvider).
	In the Rails case, this is the ClassPathProviderImpl class in ruby.railsproject.
	I will describe this class in more detail below.
	</li>
	<li> Register the ClassPathProviderImpl in your project's lookup.
	<li> In your project's <code>open</code> hook, register your class path
	with the global path registry, like this:
	<pre>
	ClassPathProviderImpl cpProvider = getLookup().lookup(ClassPathProviderImpl.class);
	GlobalPathRegistry.getDefault().register(ClassPath.BOOT, cpProvider.getProjectClassPaths(ClassPath.BOOT));
	GlobalPathRegistry.getDefault().register(ClassPath.SOURCE, cpProvider.getProjectClassPaths(ClassPath.SOURCE));
	</pre>
	</li>
	<li>
	Similarly. in your project's <code>close</code> hook, unregister the paths:
	<pre>
	ClassPathProviderImpl cpProvider = getLookup().lookup(ClassPathProviderImpl.class);
	GlobalPathRegistry.getDefault().unregister(ClassPath.BOOT, cpProvider.getProjectClassPaths(ClassPath.BOOT));
	GlobalPathRegistry.getDefault().unregister(ClassPath.SOURCE, cpProvider.getProjectClassPaths(ClassPath.SOURCE));
	</pre>
	</li>
	</ol>

	That's basically it. So the only trick here is implementing the <code>ClasspathProvider</code>.
	Take a look at the one in the Rails project, or the Web project (<code>web.project</code>), etc.
	It's not rocket science. You just have to do whatever it takes for the specific project type
	to look up the source roots, decide whether all of these are relevant for your file type
	(for example, in Web projects, I only register the web folder for JavaScript, not the src folder
	which just contains Java code) and then produce classpath implementation objects for these.
	There are utility methods to help.
	</p>
	<p>
	As I warned in the red box above, this will probably change soon.
	</p>
	</body>
	</html>