Google Git
Sign in
apache / netbeans-docs / refs/heads/asf-site / . / content / 9.0 / javadoc / org-netbeans-spi-java-hints / overview-summary.html
blob: 36f25bd606bf78370e9d286386db10c3f1d1749c [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_181) on Fri Sep 14 11:38:58 BST 2018 -->
<title>Overview (Java Hints SPI)</title>
<meta name="date" content="2018-09-14">
<link rel="stylesheet" type="text/css" href="javadoc.css" title="Style">
<script type="text/javascript" src="script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="Overview (Java Hints SPI)";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li class="navBarCell1Rev">Overview</li>
<li>Package</li>
<li>Class</li>
<li>Use</li>
<li><a href="overview-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage">org.netbeans.spi.java.hints 1.32.1 13</div>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev</li>
<li>Next</li>
</ul>
<ul class="navList">
<li><a href="index.html?overview-summary.html" target="_top">Frames</a></li>
<li><a href="overview-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<div class="header">
<h1 class="title">Java Hints SPI<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ddcc80;'><a href='http://wiki.netbeans.org/API_Stability#Devel' target='_blank'>Under Development</a></span></h1>
</div>
<div class="header">
<p>See: <a href="#overview.description">Description</a></p>
</div>
<div class="contentContainer">
<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Java Hints SPI table, listing packages, and an explanation">
<caption><span>Java Hints SPI</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Package</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tbody>
<tr class="altColor">
<td class="colFirst"><a href="org/netbeans/spi/java/hints/package-summary.html">org.netbeans.spi.java.hints</a></td>
<td class="colLast">&nbsp;</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="org/netbeans/spi/java/hints/support/package-summary.html">org.netbeans.spi.java.hints.support</a></td>
<td class="colLast">&nbsp;</td>
</tr>
</tbody>
</table>
</div>
<div class="contentContainer"><a name="overview.description">
<!-- -->
</a>
<div class="block"><p>
<p>
spi.java.hints
SPI to create custom Java hints, including code smell warnings, productivity tips, etc.
Please see the Use Cases section for a guide on how to use this SPI.
</p>
</p>
<h3>What is New (see <a href="apichanges.html">all changes</a>)?</h3>
<ul>
<!--Search for dates that are later or equal to 1997-09-01 in
.-->
<!--Checking date 2018-1-15 with count of newer 0--><!--year ok-->
<li>Jan 15 '18 <a href="apichanges.html#JavaFixUtilities.isPrimary">Added JavaFixUtilities.isPrimary() utility</a>
<p>
<p>
The utility method JavaFixUtilities.isPrimary() was added.
This API checks whether a specified tree can be used in
places where a Primary expression is required.
</p>
</p>
</li>
<!--Checking date 2015-7-27 with count of newer 1--><!--year ok-->
<li>Jul 27 '15 <a href="apichanges.html#TriggerOptions">Hint can choose to trigger for guarded code</a>
<p>
<p>
Hints triggered by Tree.Kind are not invoked for Trees which are
protected from editing (i.e. Form Builder guarded blocks). Hint implementor
can opt to be triggered even for such code, in order to e.g. collect
data.
</p>
</p>
</li>
<!--Checking date 2015-5-24 with count of newer 2--><!--year ok-->
<li>May 24 '15 <a href="apichanges.html#Hint.minSourceVersion">Hint can specify minimum source version for operation</a>
<p>
<p>
Certain hints generate source code following newer language specifications.
A hint may declare <code>minSourceVersion</code> in its <code>@Hint</code>
annotation to specify a minimum source version. Such hint will be never
invoked for files configured for earlier source level.
</p>
</p>
</li>
<!--Checking date 2013-7-14 with count of newer 3--><!--year ok-->
<li>Jul 14 '13 <a href="apichanges.html#EnhancedJavaFix">Added ability to specify sort text for JavaFix</a>
<p>
<p>
Adding to new constructors to <code>JavaFix</code> to define
the sort text for the fix.
</p>
</p>
</li>
<!--Checking date 2013-4-24 with count of newer 4--><!--year ok-->
<li>Apr 24 '13 <a href="apichanges.html#ProjectHintsJava">Defining system filesystem folder for per-project Java hints customizers</a>
<p>
<p>
Defining <code>Project/hints/java-based</code> folder, where provider for
hints customizers for Java-based projects should be stored.
</p>
</p>
</li>
<!--Checking date 2013-4-3 with count of newer 5--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2012-12-19 with count of newer 6--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2012-3-29 with count of newer 7--><!--Skipped as the amount of changes is too big-->
</ul>
<h3>Use Cases</h3>
<answer id="arch-usecases">
<p>
<h5>Creating a new Java Hint</h5>
Simple way to create a new Java hint is as follows:
<ul>
<li>Create a new class, annotate it with the <a href="org/netbeans/spi/java/hints/Hint.html" shape="rect">@Hint</a>
annotation to it.</li>
<li>Create a <code>public static ErrorDescription hint(HintContext ctx) {}</code> method in the
class. Annotate the method either with the <a href="org/netbeans/spi/java/hints/TriggerPattern.html" shape="rect">@TriggerPattern</a>
annotation (strongly recommended), or with the <a href="org/netbeans/spi/java/hints/TriggerTreeKind.html" shape="rect">@TriggerTreeKind</a>.
This method will be called when for parts of the code that match the given pattern, of for trees of the specified kinds.</li>
<li>Perform whatever checks necessary to find out whether a warning should be produced at the given place, and produce the ErrorDescription if needed.</li>
</ul>
<br>
Tips:
<ul>
<li>Always use the java.hints' <a href="org/netbeans/spi/java/hints/ErrorDescriptionFactory.html" shape="rect">ErrorDescriptionFactory</a> to produce the resulting ErrorDescription.</li>
<li>Never try to produce a custom suppress warnings "fix". Specify suppress warnings keys in the @Hint annotation.</li>
<li>If an automated transformation is to be prodived from your hint, subclass <a href="org/netbeans/spi/java/hints/JavaFix.html" shape="rect">JavaFix</a> and
use its <code>toEditorFix()</code> method to get the <code>Fix</code>, if the transformation is going to be used inside Inspect&amp;Transform.
</li>
<li>The name of the method is arbitrary, one hint can consist of more that one "triggered" method.</li>
</ul>
<h5>Creating a new Java Hint Without a Class</h5>
For simple hints, it is possible to annotate the hint method with the <a href="org/netbeans/spi/java/hints/Hint.html" shape="rect">@Hint</a> annotation.
The hint then consists of this sole method. Any number of such hints may be created in a single class.
<h5>Creating a Tests for the Newly Created Java Hint</h5>
Creating automated tests for the hints is simple: create a test class, and use
<a href="../org-netbeans-modules-java-hints-test/org/netbeans/modules/java/hints/test/api/HintTest.html" shape="rect">HintTest</a>
to setup the test, run the hint and verify that its outcomes are correct.
The tests automatically run with <code>test</code> branding, so create <code>Bundle_test.properties</code>, and add
bundle keys into it for ErrorDescription and Fix display names, to isolate the test from changes in the production
<code>Bundle.properties</code>.
<h5>Adding options to a Java Hint</h5>
To add a simple boolean option to your hint, use <a href="org/netbeans/spi/java/hints/BooleanOption.html" shape="rect">@BooleanOption</a>.
</p>
</answer>
<h3>Exported Interfaces</h3>
This table lists all of the module exported APIs
with
defined stability classifications. It is generated
based on answers to questions about the architecture
of the module. <a href="architecture-summary.html">Read them all</a>...
<a name="group-java">
<h5>Group of java interfaces</h5>
</a>
<table cellpadding="1" cellspacing="0" border="0" class="tablebg" width="100%">
<tr>
<td>
<table border="0" cellpadding="3" cellspacing="1" width="100%">
<tr class="tablersh">
<td align="CENTER" width="25%"><span class="titlectable">Interface Name</span></td><td align="CENTER" width="10%"><span class="titlectable">In/Out</span></td><td align="CENTER" width="10%"><span class="titlectable">Stability</span></td><td align="CENTER"><span class="titlectable">Specified in What Document?</span></td>
</tr>
<tr class="tabler">
<td>spi.java.hints</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Devel">Under Development</a></td><td><a name="java-spi.java.hints">
<p></p>
SPI to create custom Java hints, including code smell warnings, productivity tips, etc.
Please see the Use Cases section for a guide on how to use this SPI.
<p></p>
</a></td>
</tr>
</table>
</td>
</tr>
</table>
<p></p>
<h3>Implementation Details</h3>
<h5>Where are the sources for the module?</h5>
<p>
<p>
The sources for the module are in the
<a href="http://hg.netbeans.org/" shape="rect">NetBeans Mercurial repositories</a>.
</p>
</p>
<h5>What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?</h5>
<p>
XXX no answer for deploy-dependencies
</p>
<p>
Read more about the implementation in the <a href="architecture-summary.html">answers to
architecture questions</a>.
</p></div>
</div>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li class="navBarCell1Rev">Overview</li>
<li>Package</li>
<li>Class</li>
<li>Use</li>
<li><a href="overview-tree.html">Tree</a></li>
<li><a href="deprecated-list.html">Deprecated</a></li>
<li><a href="index-files/index-1.html">Index</a></li>
<li><a href="help-doc.html">Help</a></li>
</ul>
<div class="aboutLanguage">org.netbeans.spi.java.hints 1.32.1 13</div>
</div>
<div class="subNav">
<ul class="navList">
<li>Prev</li>
<li>Next</li>
</ul>
<ul class="navList">
<li><a href="index.html?overview-summary.html" target="_top">Frames</a></li>
<li><a href="overview-summary.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><span class="footnote">Built on September 14 2018.&nbsp;&nbsp;|&nbsp;&nbsp; Copyright &#169; 2017-2018 Apache Software Foundation. All Rights Reserved.</span></small></p>
</body>
</html>