# HG changeset patch # Parent 90657ff2e3ebc869fce1f3f98c7a8e2a8385d538 #160415: Stabilize Search API diff --git a/api.search/arch.xml b/api.search/arch.xml --- a/api.search/arch.xml +++ b/api.search/arch.xml @@ -131,14 +131,18 @@

- SearchHistory is synchronising history content through netbeans modules and it saves history to preferences. + SearchHistory + is synchronising history content through netbeans modules and it saves history to preferences.

There are two separate histories. One for search and another for replace. - When you add your propertyListener to SearchHistory - you can listen for changes in histories. + When you add your propertyListener to + SearchHistory + - you can listen for changes in histories.

- SearchHistory has methods for adding new entries and getting whole history list. + SearchHistory + has methods for adding new entries and getting whole history list.

@@ -153,32 +157,39 @@

The definition is represented by objects extending class - SearchInfoDefinition. To customize searching on - a custom node, a + + + SearchInfoDefinition + . To customize searching on a custom node, a SearchInfoDefinition 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 - SearchInfoDefinitionFactory. + + + SearchInfoDefinitionFactory + .

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 SearchInfoDefinition to all - nodes' lookups, but only one instance of SubTreeSearchOptions - have to be put into the lookup of the root node. + If so, it is not needed to put SearchInfoDefinition to all + nodes' lookups, but only one instance of + + SubTreeSearchOptions + have to be put into the lookup of the root node.

Defines abstract classes - SearchInfoDefinition, - SearchFilterDefinition, - SubTreeSearchOptions + SearchInfoDefinition, + SearchFilterDefinition, + SubTreeSearchOptions and a factory class - SearchInfoDefinitionFactory + SearchInfoDefinitionFactory @@ -192,50 +203,58 @@

Defines abstract classes that need to be implemented when creating custom providers: - SearchProvider, - SearchProvider.Presenter, - SearchResultsDisplayer, - SearchComposition + SearchProvider, + SearchProvider.Presenter, + SearchResultsDisplayer, + SearchComposition and relative classes. Classes usually used by search providers. - Contains class SearchInfo, that defines which files - should be searched (it can be retrieved from methods in - SearchInfoUtils, or UI component ScopeComboBox), - SearchListener that you should inform about events that - happen during searching, and helper classes FileInfoUtils - (getting SearchInfo objects for nodes) and - FileNameMatcher (filtering files by file name). + Contains class SearchInfo, + that defines which files should be searched (it can be retrieved from methods in + SearchInfoUtils, + or UI component controller ScopeController), + SearchListener + that you should inform about events that happen during searching, and helper classes + SearchInfoUtils + (getting SearchInfo objects for nodes) and + FileNameMatcher + (filtering files by file name). Several UI components that can be used in presenters of search @@ -251,7 +270,7 @@ Contains classes for controlling search, passing search diff --git a/api.search/src/org/netbeans/api/search/Bundle.properties b/api.search/src/org/netbeans/api/search/Bundle.properties --- a/api.search/src/org/netbeans/api/search/Bundle.properties +++ b/api.search/src/org/netbeans/api/search/Bundle.properties @@ -1,3 +1,3 @@ OpenIDE-Module-Display-Category=Infrastructure -OpenIDE-Module-Name=Search in Projects API +OpenIDE-Module-Name=Search API OpenIDE-Module-Short-Description=API for controlling search in projects and for implementing custom search providers diff --git a/api.search/src/org/netbeans/api/search/ReplacePattern.java b/api.search/src/org/netbeans/api/search/ReplacePattern.java --- a/api.search/src/org/netbeans/api/search/ReplacePattern.java +++ b/api.search/src/org/netbeans/api/search/ReplacePattern.java @@ -61,8 +61,8 @@ /** * Creates a new ReplacePattern in accordance with given parameters * - * @param searchExpression non-null String of a searched text - * @param wholeWords if true, only whole words were searched + * @param replaceExpression non-null String of a replace expression + * @param preserveCase if true, the case of original text will be preserved */ public static ReplacePattern create(String replaceExpression, boolean preserveCase) { return new ReplacePattern(replaceExpression, preserveCase); diff --git a/api.search/src/org/netbeans/api/search/package.html b/api.search/src/org/netbeans/api/search/package.html new file mode 100644 --- /dev/null +++ b/api.search/src/org/netbeans/api/search/package.html @@ -0,0 +1,70 @@ + + + + +

+ This package contains classes that can be used by modules that need + to work with Search in Projects dialog, or want to share + information about what data was recently searched. + There are also some utility classes for general usage. +

+

+ If you want to get or store recently searched items, see + SearchHistory, + SearchPattern + and ReplacePattern +

+

+ To display Find in Project dialog, and start a search with + predefine criteria, use + SearchControl + with SearchScopeOptions. +

+

+ Class SearchRoot defines + a location in a filesystem where the search should start. + RegexpUtil can create a pattern + for matching file names. These classes can be useful when implementing some custom search infrastructure. +

+ + diff --git a/api.search/src/org/netbeans/api/search/provider/package.html b/api.search/src/org/netbeans/api/search/provider/package.html new file mode 100644 --- /dev/null +++ b/api.search/src/org/netbeans/api/search/provider/package.html @@ -0,0 +1,69 @@ + + + + +

+ Classes that you may need to work with if you are implementing + a custom search provider. +

+

+ SearchInfo + defines what should be searched. It contains set of files or folders (what should be searched) + with associated + SearchFilters + (what should be skipped in those folders). +

+

+ SearchListener + is an object that will be passed to your implementation of + SearchInfo + and that you should inform about interesting events that occur during the search. +

+

+ SearchInfoUtils + contains utility methods for creation of search info for nodes or for files. + FileNameMatcher + matches files to current search options. +

+ + diff --git a/api.search/src/org/netbeans/api/search/ui/SearchPatternController.java b/api.search/src/org/netbeans/api/search/ui/SearchPatternController.java --- a/api.search/src/org/netbeans/api/search/ui/SearchPatternController.java +++ b/api.search/src/org/netbeans/api/search/ui/SearchPatternController.java @@ -323,7 +323,7 @@ * * @param comboBox Combo box to control and display the match type. The * model of the combo box can contain only items of type {@link MatchType}. - * {@link MatchType.LITERAL} and {@link MatchType.REGEXP} are mandatory in + * {@link MatchType#LITERAL} and {@link MatchType#REGEXP} are mandatory in * the model. * * @since api.search/1.11 diff --git a/api.search/src/org/netbeans/api/search/ui/package.html b/api.search/src/org/netbeans/api/search/ui/package.html new file mode 100644 --- /dev/null +++ b/api.search/src/org/netbeans/api/search/ui/package.html @@ -0,0 +1,56 @@ + + + + +

+ This package contains class ComponentUtils + that can adjust fresh UI components to be used in panels for + SearchProvider.Presenter. +

+

+ The advantage of modifying of existing components and returning + controller objects (instead of using subclasses of swing components) + is that it can be comfortably used with NetBeasn GUI Builder. +

+ + diff --git a/api.search/src/org/netbeans/spi/search/package.html b/api.search/src/org/netbeans/spi/search/package.html new file mode 100644 --- /dev/null +++ b/api.search/src/org/netbeans/spi/search/package.html @@ -0,0 +1,61 @@ + + + + +

+ 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. For this, use + SearchInfoDefinition + or SubTreeSearchOptions, + and possibly SearchFilterDefinition + and SearchInfoDefinitionFactory. +

+

+ To add a custom search scope to Find in Projects dialog, + you will need to subclass + SearchScopeDefinition + and SearchScopeDefinitionProvider. +

+ + diff --git a/api.search/src/org/netbeans/spi/search/provider/package.html b/api.search/src/org/netbeans/spi/search/provider/package.html new file mode 100644 --- /dev/null +++ b/api.search/src/org/netbeans/spi/search/provider/package.html @@ -0,0 +1,55 @@ + + + + +

+ This package contains classes that are needed to add a custom panel + to Find in Projects dialog, that can have customized search + criteria, search algorithm and results panel. +

+

+ The entry point for such custom search provider is class + SearchProvider. +

+ + diff --git a/nbbuild/build.properties b/nbbuild/build.properties --- a/nbbuild/build.properties +++ b/nbbuild/build.properties @@ -146,6 +146,7 @@ api.visual,\ api.java,\ api.java.classpath,\ + api.search,\ java.platform,\ java.project,\ java.source,\ @@ -168,7 +169,6 @@ nbjunit,\ jellytools.platform,\ jellytools.ide,\ - api.search,\ core.netigso,\ o.n.swing.outline,\ o.n.swing.tabcontrol,\ diff --git a/o.openidex.util/src/org/openidex/resources/Bundle.properties b/o.openidex.util/src/org/openidex/resources/Bundle.properties --- a/o.openidex.util/src/org/openidex/resources/Bundle.properties +++ b/o.openidex.util/src/org/openidex/resources/Bundle.properties @@ -40,7 +40,7 @@ # Version 2 license, then the option applies only if the new code is # made subject to such option by the copyright holder. -OpenIDE-Module-Name=Search API +OpenIDE-Module-Name=Deprecated, old search API OpenIDE-Module-Display-Category=Infrastructure OpenIDE-Module-Short-Description=Search API for use by various modules. OpenIDE-Module-Long-Description=\