blob: 89e255a94b037597ed66a53c5dd2547ad9df81fd [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:00 BST 2018 -->
<title>Overview (Search API)</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 (Search API)";
}
}
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.api.search 1.23.1 </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">Search API<br/><span style='font-style:normal; font-size:medium; font-weight:normal; background-color:#ffffff;'><a href='http://wiki.netbeans.org/API_Stability#Stable' target='_blank'>Stable</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="Search API table, listing packages, and an explanation">
<caption><span>Search API</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/api/search/package-summary.html">org.netbeans.api.search</a></td>
<td class="colLast">
<div class="block">
This package contains classes that can be used by modules that need
to work with <i>Search in Projects</i> dialog, or want to share
information about what data was recently searched.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="org/netbeans/api/search/provider/package-summary.html">org.netbeans.api.search.provider</a></td>
<td class="colLast">
<div class="block">
Classes that you may need to work with if you are implementing
a custom search provider.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="org/netbeans/api/search/ui/package-summary.html">org.netbeans.api.search.ui</a></td>
<td class="colLast">
<div class="block">
Helpers for creating UI controls for your search provider that are
similar to controls in the default provider.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><a href="org/netbeans/spi/search/package-summary.html">org.netbeans.spi.search</a></td>
<td class="colLast">
<div class="block">
This package contains classes that you can subclass and register to
lookups of nodes if you want to specify how the nodes should be
searched.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><a href="org/netbeans/spi/search/provider/package-summary.html">org.netbeans.spi.search.provider</a></td>
<td class="colLast">
<div class="block">
This package contains classes that are needed to add a custom panel
to <i>Find in Projects</i> dialog, that can have customized search
criteria, search algorithm and results panel.</div>
</td>
</tr>
</tbody>
</table>
</div>
<div class="contentContainer"><a name="overview.description">
<!-- -->
</a>
<div class="block"><p>
<p>
There are three goals:
</p>
<ul>
<li>
The module offers an SPI which can be used to make nodes
searchable by "Search in Projects" dialog, and to specify
how the nodes should be searched, and API which makes
implementation of the SPI easier.
</li>
<li>
There is also an SPI for custom search providers.
Search provider is an algorithm for searching and a set of
UI components for setting search options and displaying
results. Each provider is represented by a tab in "Search in
Projects" dialog. The SPI is accompanied by API for getting
info about search settings for nodes, for creating UI for
search dialog, and for communicating with
search results window.
</li>
<li>
Provide API for opening Find in Projects and Replace in Projects
dialogs and for starting search programatically.
</li>
</ul>
<p>
The module also contains UI for Find (Replace) in Projects dialog
and search results window, and implementation of default search
provider.
</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 2013-2-6 with count of newer 0--><!--year ok-->
<li>Feb 6 '13 <a href="apichanges.html#ComponentUtils_adjustPanelsForOptions">Added method ComponentUtils.adjustPanelsForOptions</a>
<p>
<p>
Controls for specifying search scope options can now be
split into two panels - one for scope options, and one for
file name options.
</p>
<p>
Class ComponentUtils has new method
adjustPanelsForOptions(JPanel, JPanel, boolean,
FileNameController), that takes the two panels. It can be
used instead of adjustPanelForOptions(JPanel, boolean,
FileNameController), that puts all controls into a single
panel.
</p>
<p>
Class ScopeOptionsController has new method
getFileNameComponent() to get the panel with controls
related to file name. (The panel related to search scope can
be get using getComponent()).
</p>
</p>
</li>
<!--Checking date 2013-1-29 with count of newer 1--><!--year ok-->
<li>Jan 29 '13 <a href="apichanges.html#SearchPattern_MatchType">Search pattern supports three match types (literal, basic wildcards, regexp)</a>
<p>
<p>
Before, the search pattern distinguished two match types:
Regular Expression and Standard. The standard meant that the
text was searched literally in editor search, and that the
searched text could contain basic wildcards (* and ?) in
Find in Projects.
</p>
<p>
Now, the Search pattern can specify exact match type:
Regular Expression, Basic Wildcards and Literal. Basic
wildcards are not supported by Editor search, but the
fallback to Literal Search is transparent for the editor.
</p>
<p>
To support extra match types, a few parts have to be added
to the API:
</p>
<ul>
<li>Enumeration SearchPattern.MatchType which contains
all supported match types
</li>
<li>Method SearchPattern.create(String searchExpression,
boolean wholeWords, boolean matchCase,
MatchType matchType)
</li>
<li>Method SearchPattern.getMatchType() and
SearchPattern.changeMatchType(MatchType)
</li>
<li>Method SearchPatternController.bindMatchTypeComboBox(
JComboBox) for binding match type property to a combo
box.
</li>
</ul>
</p>
</li>
<!--Checking date 2013-1-29 with count of newer 1--><!--year ok-->
<li>Jan 29 '13 <a href="apichanges.html#SearchScopeDefinition_getIcon">Added method getIcon to class SearchScopeDefinition</a>
<p>
<p>
Search scope can define an icon that will be shown in the
UI, usually in the combo box for search scope selection.
</p>
<p>
To use a custom scope icon, override method
SearchScopeDefinition.getIcon().
</p>
</p>
</li>
<!--Checking date 2012-11-20 with count of newer 3--><!--year ok-->
<li>Nov 20 '12 <a href="apichanges.html#ReplaceHistory">Added ReplacePattern and replace history to SearchHistory class</a>
<p>
<p>
Search History is extended for replace history.
</p>
<p>
New ReplacePattern is a wrap class for replace expression.
</p>
</p>
</li>
<!--Checking date 2012-6-25 with count of newer 4--><!--year ok-->
<li>Jun 25 '12 <a href="apichanges.html#SearchResultsDisplayer-closed">Added method SearchResultsDisplayer.closed()</a>
<p>
<p>
The new <code>SearchResultsDisplayer.closed()</code> is
called when the results panel is closed by the user. It can
be overriden to release all resouces held by the panel.
</p>
<p>
Before this change, <code>HierarchyListener</code>s were
used to detect detaching of search results panels. But it
is quite complicated as the panels can be often detached and
attached again when they are moved from a simple pane to a
tabbed pane or vice versa.
</p>
</p>
</li>
<!--Checking date 2012-4-27 with count of newer 5--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2012-4-20 with count of newer 6--><!--Skipped as the amount of changes is too big-->
<!--Checking date 2012-4-20 with count of newer 6--><!--Skipped as the amount of changes is too big-->
</ul>
<h3>Use Cases</h3>
<answer id="arch-usecases">
<h5>Search History</h5>
<p>
<code><a href="org/netbeans/api/search/SearchHistory.html" shape="rect">SearchHistory</a></code>
is synchronising history content through netbeans modules and it saves history to preferences.
</p>
<p>
There are two separate histories. One for search and another for replace.
When you add your propertyListener to
<code><a href="org/netbeans/api/search/SearchHistory.html" shape="rect">SearchHistory</a></code>
- you can listen for changes in histories.
</p>
<p>
<code><a href="org/netbeans/api/search/SearchHistory.html" shape="rect">SearchHistory</a></code>
has methods for adding new entries and getting whole history list.
</p>
<h5>SearchInfo API &amp; SPI</h5>
<p>
This use-case was formerly covered by module
org.openidex.search.
</p>
<p>
The SearchInfo API+SPI allows other modules to specify whether
and how should nodes they define be searched.
</p>
<p>
The definition is represented by objects extending class
<code>
<a href="org/netbeans/spi/search/SearchInfoDefinition.html" shape="rect">
SearchInfoDefinition</a>
</code>. To customize searching on a custom node, a
<code>SearchInfoDefinition</code> object must be added to the node's lookup.
In most cases, there is no need to define own class extending the
class - one can use factory methods of class
<code>
<a href="org/netbeans/spi/search/SearchInfoDefinitionFactory.html" shape="rect">
SearchInfoDefinitionFactory</a>
</code>.
</p>
<p>
In some cases implementators may need to apply the same set
of SearchFilterDefinitions in the whole subtree of a node.
If so, it is not needed to put <code>SearchInfoDefinition</code> to all
nodes' lookups, but only one instance of <code>
<a href="org/netbeans/spi/search/SubTreeSearchOptions.html" shape="rect">
SubTreeSearchOptions</a>
</code> have to be put into the lookup of the root node.
</p>
<api category="stable" group="java" name="SearchInfoSPI" type="export" url="org/netbeans/spi/search/package-summary.html">
Defines abstract classes
<code><a href="org/netbeans/spi/search/SearchInfoDefinition.html" shape="rect">SearchInfoDefinition</a></code>,
<code><a href="org/netbeans/spi/search/SearchFilterDefinition.html" shape="rect">SearchFilterDefinition</a></code>,
<code><a href="org/netbeans/spi/search/SubTreeSearchOptions.html" shape="rect">SubTreeSearchOptions</a></code>
and a factory class
<code><a href="org/netbeans/spi/search/SearchInfoDefinitionFactory.html" shape="rect">SearchInfoDefinitionFactory</a></code>
</api>
<h5>Enhance IDE searching features</h5>
<p>
People that want to enhance IDE searching features (with custom
search criteria or specialized algorithms) can add a new tab to
the "Search in Projects" dialog.
</p>
<p>
They need to implement several classes:
</p>
<ul>
<li>
<code><a href="org/netbeans/spi/search/provider/SearchProvider.html" shape="rect">SearchProvider</a></code>
to register the new search feature to the IDE or platform application.
</li>
<li>
<code><a href="org/netbeans/spi/search/provider/SearchProvider.Presenter.html" shape="rect">SearchProvider.Presenter</a></code>
that creates visual component for adding to the search dialog and that can interact with dialog buttons.
</li>
<li>
<code><a href="org/netbeans/spi/search/provider/SearchResultsDisplayer.html" shape="rect">SearchResultsDisplayer</a></code>
to show search results to the user.
</li>
<li>
<code><a href="org/netbeans/spi/search/provider/SearchComposition.html" shape="rect">SearchComposition</a></code>
that encapsulates setting and state of searches, provide access to result displayer, and is able to start
and terminate the search.
</li>
</ul>
<api category="stable" group="java" name="SearchProviderSPI" type="export" url="org/netbeans/spi/search/provider/package-summary.html">
Defines abstract classes that need to be implemented when
creating custom providers:
<code><a href="org/netbeans/spi/search/provider/SearchProvider.html" shape="rect">SearchProvider</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchProvider.Presenter.html" shape="rect">SearchProvider.Presenter</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchResultsDisplayer.html" shape="rect">SearchResultsDisplayer</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchComposition.html" shape="rect">SearchComposition</a></code>
and relative classes.
</api>
<api category="stable" group="java" name="SearchProviderAPI" type="export" url="org/netbeans/api/search/provider/package-summary.html">
Classes usually used by search providers.
Contains class <code><a href="org/netbeans/api/search/provider/SearchInfo.html" shape="rect">SearchInfo</a></code>,
that defines which files should be searched (it can be retrieved from methods in
<code><a href="org/netbeans/api/search/provider/SearchInfoUtils.html" shape="rect">SearchInfoUtils</a></code>,
or UI component controller <code><a href="org/netbeans/api/search/ui/ScopeController.html" shape="rect">ScopeController</a></code>),
<code><a href="org/netbeans/api/search/provider/SearchListener.html" shape="rect">SearchListener</a></code>
that you should inform about events that happen during searching, and helper classes
<code><a href="org/netbeans/api/search/provider/SearchInfoUtils.html" shape="rect">SearchInfoUtils</a></code>
(getting SearchInfo objects for nodes) and
<code><a href="org/netbeans/api/search/provider/FileNameMatcher.html" shape="rect">FileNameMatcher</a></code>
(filtering files by file name).
</api>
<api category="stable" group="java" name="SearchProviderUIAPI" type="export" url="org/netbeans/api/search/ui/package-summary.html">
Several UI components that can be used in presenters of search
providers, and factory method for creating them.
</api>
<h5>Search in Projects API</h5>
<p>
This API enables other modules to open Find in Projects dialog
with some pre-defined criteria and to start searching
programatically.
</p>
<api category="stable" group="java" name="SearchAPI" type="export" url="org/netbeans/api/search/package-summary.html">
Contains classes for controlling search, passing search
criteria, and some helper classes.
</api>
</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>SearchInfoSPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="java-SearchInfoSPI"><a href="org/netbeans/spi/search/package-summary.html">
.../netbeans/spi/search/package-summary.html</a>
<p></p>
<p></p>
Defines abstract classes
<code><a href="org/netbeans/spi/search/SearchInfoDefinition.html" shape="rect">SearchInfoDefinition</a></code>,
<code><a href="org/netbeans/spi/search/SearchFilterDefinition.html" shape="rect">SearchFilterDefinition</a></code>,
<code><a href="org/netbeans/spi/search/SubTreeSearchOptions.html" shape="rect">SubTreeSearchOptions</a></code>
and a factory class
<code><a href="org/netbeans/spi/search/SearchInfoDefinitionFactory.html" shape="rect">SearchInfoDefinitionFactory</a></code>
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>SearchProviderSPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="java-SearchProviderSPI"><a href="org/netbeans/spi/search/provider/package-summary.html">
.../spi/search/provider/package-summary.html</a>
<p></p>
<p></p>
Defines abstract classes that need to be implemented when
creating custom providers:
<code><a href="org/netbeans/spi/search/provider/SearchProvider.html" shape="rect">SearchProvider</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchProvider.Presenter.html" shape="rect">SearchProvider.Presenter</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchResultsDisplayer.html" shape="rect">SearchResultsDisplayer</a></code>,
<code><a href="org/netbeans/spi/search/provider/SearchComposition.html" shape="rect">SearchComposition</a></code>
and relative classes.
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>SearchProviderAPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="java-SearchProviderAPI"><a href="org/netbeans/api/search/provider/package-summary.html">
.../api/search/provider/package-summary.html</a>
<p></p>
<p></p>
Classes usually used by search providers.
Contains class <code><a href="org/netbeans/api/search/provider/SearchInfo.html" shape="rect">SearchInfo</a></code>,
that defines which files should be searched (it can be retrieved from methods in
<code><a href="org/netbeans/api/search/provider/SearchInfoUtils.html" shape="rect">SearchInfoUtils</a></code>,
or UI component controller <code><a href="org/netbeans/api/search/ui/ScopeController.html" shape="rect">ScopeController</a></code>),
<code><a href="org/netbeans/api/search/provider/SearchListener.html" shape="rect">SearchListener</a></code>
that you should inform about events that happen during searching, and helper classes
<code><a href="org/netbeans/api/search/provider/SearchInfoUtils.html" shape="rect">SearchInfoUtils</a></code>
(getting SearchInfo objects for nodes) and
<code><a href="org/netbeans/api/search/provider/FileNameMatcher.html" shape="rect">FileNameMatcher</a></code>
(filtering files by file name).
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>SearchProviderUIAPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="java-SearchProviderUIAPI"><a href="org/netbeans/api/search/ui/package-summary.html">
.../api/search/ui/package-summary.html</a>
<p></p>
<p></p>
Several UI components that can be used in presenters of search
providers, and factory method for creating them.
<p></p>
</a></td>
</tr>
<tr class="tabler">
<td>SearchAPI</td><td>Exported</td><td><a href="http://wiki.netbeans.org/API_Stability#Stable">Stable</a></td><td><a name="java-SearchAPI"><a href="org/netbeans/api/search/package-summary.html">
.../netbeans/api/search/package-summary.html</a>
<p></p>
<p></p>
Contains classes for controlling search, passing search
criteria, and some helper classes.
<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>
No extra declaration is required.
</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.api.search 1.23.1 </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>