|
This project is good for implementators of nodes to define how files under this node should be searched. For example, if you implement a custom project type, you can define which folders should be searched when the project is in the current search scope.
It is also good for people who want to add a custom tab into the "Search in projects" dialog. For example, implementators of platform applications can add form with criteria for searching in a database.
Question (arch-overall): Describe the overall architecture. Answer:There are three goals:
The module also contains UI for Find (Replace) in Projects dialog and search results window, and implementation of default search provider.
Question (arch-usecases): Describe the main use cases of the new API. Who will use it under what circumstances? What kind of code would typically need to be written to use the module? Answer:
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.
SearchHistory
has methods for adding new entries and getting whole history list.
This use-case was formerly covered by module org.openidex.search.
The SearchInfo API+SPI allows other modules to specify whether and how should nodes they define be searched.
The definition is represented by objects extending class
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
.
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.
SearchInfoDefinition,
SearchFilterDefinition,
SubTreeSearchOptions
and a factory class
SearchInfoDefinitionFactory
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.
They need to implement several classes:
SearchProvider
to register the new search feature to the IDE or platform application.
SearchProvider.Presenter
that creates visual component for adding to the search dialog and that can interact with dialog buttons.
SearchResultsDisplayer
to show search results to the user.
SearchComposition
that encapsulates setting and state of searches, provide access to result displayer, and is able to start
and terminate the search.
SearchProvider,
SearchProvider.Presenter,
SearchResultsDisplayer,
SearchComposition
and relative classes.
SearchProviderAPI
-
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 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).
SearchProviderUIAPI
-
Several UI components that can be used in presenters of search
providers, and factory method for creating them.
This API enables other modules to open Find in Projects dialog with some pre-defined criteria and to start searching programatically.
SearchAPI - Contains classes for controlling search, passing search criteria, and some helper classes. Question (arch-time): What are the time estimates of the work? Answer:The work is almost complete. Several test has to be written and completed. SPI and API for search scopes may be needed in the future. The API can be finished in a few days. Search control needs to be implemented.
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented? Answer:There will be several tests for API classes, private helpers and for private implementations of SPI classes. All test are JUnit unit tests.
Question (arch-where): Where one can find sources for your module? Answer:
The sources for the module are in the Apache Git repositories or in the GitHub repositories.
These modules are required in project.xml:
There are no such dependencies.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each? Answer:It runs on all platforms with a JRE 1.4+. It runs in the same way on each.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)? Answer:1.6
Question (dep-jrejdk): Do you require the JDK or is the JRE enough? Answer:JRE is enough.
Only one JAR.
Question (deploy-nbm): Can you deploy an NBM via the Update Center? Answer:XXX no answer for deploy-nbm
Question (deploy-shared): Do you need to be installed in the shared location only, or in the user directory only, or can your module be installed anywhere? Answer:Does not matter.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public? Answer:Yes. There are some private packages with default implementation of abstract classes and some helper classes. Only API and SPI packages are public.
Question (deploy-dependencies): What do other modules need to do to declare a dependency on this one, in addition to or instead of the normal module dependency declaration (e.g. tokens to require)? Answer:No extra declaration is required.
Yes
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow? Answer:The module does not implement any standards.
Question (compat-version): Can your module coexist with earlier and future versions of itself? Can you correctly read all old settings? Will future versions be able to read your current settings? Can you read or politely ignore settings stored by a future version? Answer:Only history of search patterns and search scope options is persisted. Stored data are not critical.
Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product? Answer:This API deprecates module org.openidex.search.
The original API did not support custom search providers and caused some performance problems (now it is possible to pass search options to search iterator, but all files had to be iterated over in the old API). It is also possible to get list of root folder of the search scope, which can be used by alternative search providers.
java.io.File directly?
Answer:
Not currently, but it can be used later to improve performance.
Question (resources-layer): Does your module provide own layer? Does it create any files or folders in it? What it is trying to communicate by that and with which components? Answer:No. But it can change if search-related code from utilities is moved here.
Question (resources-read): Does your module read any resources from layers? For what purpose? Answer:No.
Question (resources-mask): Does your module mask/hide/override any resources provided by other modules in their layers? Answer:No.
Question (resources-preferences): Does your module uses preferences via Preferences API? Does your module use NbPreferences or or regular JDK Preferences ? Does it read, write or both ? Does it share preferences with other modules ? If so, then why ? Answer:Regular JDK Preferences is used in SearchHistory to store history info. It reads and writes it. It is not shared with other modules, SearchInfo is public instead.
org.openide.util.Lookup
or any similar technology to find any components to communicate with? Which ones?
Answer:
Lookup is used to find SearchInfoDefinition and SubTreeSearchOptions instances in lookups of nodes, and to get registered SearchProvider and SearchScopeDefinitionProvider instances in the default lookup.
Question (lookup-register): Do you register anything into lookup for other code to find? Answer:No.
Question (lookup-remove): Do you remove entries of other modules from lookup? Answer:No.
System.getProperty) property?
On a similar note, is there something interesting that you
pass to java.util.logging.Logger? Or do you observe
what others log?
Answer:
No.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components? Answer:No.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use? Answer:No.
Question (exec-classloader): Does your code create its own class loader(s)? Answer:No.
Question (exec-reflection): Does your code use Java Reflection to execute other code? Answer:No.
Question (exec-privateaccess): Are you aware of any other parts of the system calling some of your methods by reflection? Answer:No.
Question (exec-process): Do you execute an external process from your module? How do you ensure that the result is the same on different platforms? Do you parse output? Do you depend on result code? Answer:No.
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof,
work with java.lang.Class, etc.)?
Answer:
Operator instanceof is used only in equals method of class SearchPattern.
Question (exec-threading): What threading models, if any, does your module adhere to? How the project behaves with respect to threading? Answer:Searches are performed in non-EDT threads. Interaction with EDT is provided by AtomicBoolean objects for termination, SearchListener for showing search progress and events, and SearchResultsDisplayer for displaying search results.
Question (security-policy): Does your functionality require modifications to the standard policy file? Answer:No.
Question (security-grant): Does your code grant additional rights to some other code? Answer:No.
Files are only traversed by SimpleSearchIterator. They can be read by SearchProviders that check their contents.
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop? Answer:None.
Question (format-clipboard): Which data flavors (if any) does your code read from or insert to the clipboard (by access to clipboard on means calling methods onjava.awt.datatransfer.Transferable?
Answer:
No interaction with clipboard yet. This can change in the future if search-related code from module utilities is moved to this module.
No.
Question (perf-exit): Does your module run any code on exit? Answer:No.
Question (perf-scale): Which external criteria influence the performance of your program (size of file in editor, number of files in menu, in source directory, etc.) and how well your code scales? Answer:The performance is influenced mainly by file system.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle? Answer:Traversing a lot of files and directories can take a long time. Finding a lot of matches can cause problems, but it should be handled by search providers.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc. Answer:
Amount of memory consumed by implementations of class
SearchInfoDefinition, produced by class
SearchInfoDefinitionFactory,
is related to the maximum nesting level of folder/nodes
and to the maximum number of folders/nodes in each level.
Except for very extreme conditions, the amount of memory
is not essential.
Term "extreme conditions" comprises:
SearchInfo objects
Memory footprint of SearchInfo implementations returned by
factory class SearchInfoFactory is low. This may not be true
for custom plugged-in implementations.
No.
Question (perf-progress): Does your module execute any long-running tasks? Answer:Searching for the next file in SimpleSearchIterator can take long time, but this operation is invoked by search providers, not by code in this module. There is an assertion for not being run in EDT in the hasNext() method of that iterator.
Question (perf-huge_dialogs): Does your module contain any dialogs or wizards with a large number of GUI controls such as combo boxes, lists, trees, or text areas? Answer:The module contains Find in Projects dialog and Search Results Window.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic? Answer:No.
Question (perf-spi): How the performance of the plugged in code will be enforced? Answer:Only by notes in javadoc documentation for SearchFilterDefinition.