SearchApiChangesFor72
The main goals of this proposed API change are:
- Create a new API module that will replace org.openidex.search.
- Simplify defining file filters for project folders (bug 202171, new class SubTreeSearchOptions).
- Enable to start a new search or to open search dialog programatically (new class SearchControl).
- Prepare SPI that will allow people (platform users) to implement custom search providers.
Contents |
Simplify Defining File Filters in Project Trees
Current state
If you want to provide a custom SearchInfo for project folder tree, you need to add a new custom SearchInfo instance to every node in the project tree.
See http://netbeans.org/bugzilla/show_bug.cgi?id=202171.
Proposed change
Newly introduced class SubTreeSearchOptions contains settings (currently only a set of SearchFilterDefinitions) that are common to the whole subtree. If a search is started from a node, the nearest ancestor node with NodeSearchOptions will define search settings.
Please, also see alternatives.
Programmatic Control
Current state
It is not possible to open standard search dialog or to start a search programatically.
Proposed change
Instances of class SearchControl can be used to open dialogs or start searches (there will be probably only one implementation).
This API will be used in find/replace bar in editor (user finding in one document can use current search options to extend the search to all files in opened projects, for example), or in Search History views.
Custom Search Providers
Current state
Search criteria can be extended using class SearchType. SearchType seems to have no available documentation, and it is probably not used anywhere. Its superclass is deprecated.
The way how files are traversed, matched and how results are displayed cannot be customized
The code in module User Utilities is quite monolithic, the same algorithm for searching and matching is used for all search settings, which causes bad performance.
Search API is quite old and its API stability is still "under development".
Proposed changes
Deprecate class SearchType and its relative SearchGroup.
Use new SPI and API for implementing search providers.
Split searching into smaller, customizable areas:
- SearchProvider - search feature registered to applications
- is enabled (depending on platform, available modules)
- supports replacing (its presenter should appear in replace dialog)
- name (title of tab in search/replace dialog)
- help ID
- SearchProvider.Presenter - user Interface in a tab in Search dialog
- create UI component
- compose search - called when search is triggered in the search panel
- current settings specified in the UI component is usable for starting search
- add usability change listener (for enabling/disabling OK button as settings **change in the UI component)
- clean (called when search dialog is closed to relase resouces, remove triggers etc.)
- SearchInfo - hold information about searching under a node.
- getFilesToSearch - iterates over all files in the search scope with matching name.
- getSearchRoot - get search roots - root folder (or file) and associated SearchFilters.
- SearchResultsDisplayer - display results and inform about various events
- create visual component (that will be added to a tab in search results window)
- add matching object (and update model of visual component)
- title of tab in search results window
- static method that can create default displayer, given an object that can create nodes matching objects (class SearchResultsDisplayer.NodeDisplayer)
- SearchListener - listener that is informed about events during searching
- SearchComposition - and object holding search algorithm, criteria and settings.
Helper classes:
- SearchScopeOptions - class holding default search options
- file name pattern
- search in archives
- search in generated
- and similar
- RegexpUtil - for creatign regular expression patterns for file name patterns
- Created from org.netbeans.modules.search.RegexpMaker
UI Components:
Classes that can be useful when building a visual component for SearchProvider.Presenter.
- ComponentFactory - factory for components that can be added to panels with **search settings
- create combo-box for selecting search scope
- create combo-box for entering file name pattern
- create panel containing standard searcher settings
- FileNameComboBox - combo box that shows (all files) text in gray color if no explicit text is selected, and that sets its color to red if the pattern is invalid
- getFileNamePattern
- set/get regular expression name
- is all-files info displayed
- display/hide all files info
- add/remove pattern change listener
- ScopeComboBox - combo box for selecting one of currently available search scopes. It listens for changes in global selection and updates the list if necessary
- getSearchInfo - get search info for currently selected search scope
- clean - release resources, remove listeners
- ScopeSettingsPanel - panel containing controls for settings standard search options
- get/set search in archives
- get/set search in generated resources
- get/set use ignore list
- get/set file-name regular expression mode
Alternatives
Provider SPI
If API reviewers find proposed API for search providers useless, new classes can be still used internally in module User Utilities.
NodeSearchOptions
Instead of using NodeSearchOptions, FileObjectFilters (one or more) can be put directly into lookups of nodes.
Plans
- Implement optimized search iterators (e.g. for versioned sources)
- Improve default search results window - use Nodes API, flat/tree view
- Show list of events collected by SearchListener in the UI
Links
Bugzilla issue (with attached example module): http://netbeans.org/bugzilla/show_bug.cgi?id=207436
