|
|
QuickSearch API and its implementations provides way for end user to learn system earlier and easier and also to find various things in the system more quickly, conveniently and in standard way. Main project page is on nb wiki, http://wiki.netbeans.org/QuickSearch
Question (arch-overall): Describe the overall architecture. Answer:Quick Search API in infrastrcuture which enables module clients to plug into Quick Search UI and provide results of search that end user performed in UI. Quick Search UI is represented by a small text field in toolbar area on right hand side, with asociated popup window to show search results.
Clients that want to extend Quick Search capabilities and provide data to search in are expected to implement SearchProvider SPI.
SearchProvider implementations are registered through module's xml layer file, as explained in SearchProvider SPI javadoc and detailed Instantiation rules.
Main task of SearchProvider implementations is to evaluate input SearchRequest, perform search in its data model and feed SearchResponse response object by results apropriate for given request.
quicksearch.web.site - Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify website to restrict the web search to. When set to e.g. NetBeans.org then the web search provider will search for given text in web pages from NetBeans.org site only. quicksearch.web.url_patterns - Resource name from org.netbeans.modules.quicksearch.web.Bundle where it is possible to specify a comma separated list of regular expressions that the search results URLs must contain. When set to e.g. ".*docs/myapp.*,.*tutorials/myapp.*" then all the search results will have either "docs/myapp" or "tutorials/myapp" anywhere in the URL. 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:
SearchProvider.evaluate
method
like suggested in its javadoc.
<folder name="QuickSearch"> <folder name="Category1_ID"> <attr name="position" intvalue="300"/> <file name="org-netbeans-module1-package1-Provider1Impl.instance"/> </folder> <folder name="Category2_ID"> <!--Attribute for localization - provide localized display name of category!--> <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/> <!--Attribute for command prefix - used to narrow search to this category only!--> <attr name="command" stringvalue="p"/> <!--Attribute for category ordering!--> <attr name="position" intvalue="200"/> <!--Note that multiple providers can contribute to one category!--> <file name="org-netbeans-module2-package2-Provider2Impl.instance"/> <file name="org-netbeans-module2-package3-Provider3Impl.instance"/> </folder> </folder>Syntax explanation:
Quick Search UI shows search results divided into visually separeted sections,
called categories. Several SearchProvider
implementations may decide to display
their results in one shared category of results in Quick Search UI.
In order to share category, module writers have to agree on shared category and its properties, especially its name. It means that all providers (possibly in different NetBeans modules) need to be registered under the same folder, as shown below:
SharedCategory
such as
display name, position and command prefix.
<folder name="QuickSearch"> <folder name="SharedCategory"> <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.yourmodule.YourBundle"/> <attr name="command" stringvalue="p"/> <attr name="position" intvalue="200"/> <file name="org-netbeans-module1-package1-Provider1Impl.instance"> <attr name="position" intvalue="300"/> </file> </folder> </folder>
SharedCategory
,
as they were already defined by Provider 1.
Note that module dependency on the module of Provider 1 is needed
to ensure that SharedCategory
is fully defined.
<folder name="QuickSearch"> <folder name="SharedCategory"> <file name="org-netbeans-module2-package2-Provider2Impl.instance"/> <attr name="position" intvalue="200"/> </file> </folder> </folder>
<folder name="QuickSearch"> <folder name="SharedCategory"> <file name="org-netbeans-module2-package3-Provider3Impl.instance"/> <attr name="position" intvalue="100"/> </file> </folder> </folder>
FirstCategory
to be first, and SecongCategory
to be second :),
which means that FirstCategory
and its results will be
displayed above Secondcategory
in QuickSearch results window.
<folder name="QuickSearch"> <folder name="SecondCategory"> <attr name="position" intvalue="300"/> ... </folder> <folder name="FirstCategory"> <attr name="position" intvalue="200"/> ... </folder> </folder>
spi.quicksearch
module, so its functionality is automatically always available by default.
However, if your module wants to disable "Recent Searches" or any other
category, follow the steps below:
spi,quicksearch
,
on which you probably already depend.
<folder name="QuickSearch"> <folder name="Recent_hidden"> </folder> </folder>"Recent" is a name of category for "Recent Searches" provider and by appending "_hidden" suffix you are telling system to "hide" it. This technique can be used also to disable invidual search providers.
<folder name="Toolbars"> <folder name="QuickSearch"> <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/> <file name="org-netbeans-modules-quicksearch-QuickSearchAction.shadow"> <attr name="originalFile" stringvalue="Actions/Edit/org-netbeans-modules-quicksearch-QuickSearchAction.instance"/> </file> </folder> </folder>
com.myapp.mymodule.MyBundle
in the xml registration
above with path to your properties file, in which you'll define
localized name of Quick Search toolbar:
Toolbars/QuickSearch=Quick Search
By default, providers for searching in actions and recent searches will be enabled. Web search provider is disabled by default, see use case below for info how to turn it on.
<folder name="QuickSearch"> <folder name="WebSearch"> <!--Attribute for localization - provide localized display name of category!--> <attr name="SystemFileSystem.localizingBundle" stringvalue="com.myapp.mymodule.MyBundle"/> <!--Attribute for command prefix - used to narrow search to this category only!--> <attr name="command" stringvalue="g"/> <!--Attribute for category ordering!--> <attr name="position" intvalue="200"/> <!--Note that multiple providers can contribute to one category!--> <file name="org-netbeans-modules-quicksearch-web-WebQuickSearchProviderImpl.instance"/> </folder> </folder>You can also add branding for
org.netbeans.modules.quicksearch.web
Bundle to restrict
the search to a particular site only:
quicksearch.web.site=mywebsite.comAnd you can also restrict the search to some parts your website only:
quicksearch.web.url_patterns=mywebsite.com/docs,mywebsite.com/files/tutorials
Border
instance into
UIManager
under key nb.quicksearch.border
.
Question (arch-time):
What are the time estimates of the work?
Answer:
Design two weeks, implementation of API and basic content providers about 4-5 weeks, stabilization three weeks, all estimates in manwork. Initial version should be available in release 6.5 M1, full version in release 6.5.
Question (arch-quality): How will the quality of your code be tested and how are future regressions going to be prevented? Answer:There are unit tests in test package.
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:
No external dependencies.
Question (dep-platform): On which platforms does your module run? Does it run in the same way on each? Answer:Works on all platforms, no OS dependency.
Question (dep-jre): Which version of JRE do you need (1.2, 1.3, 1.4, etc.)? Answer:JRE 1.5 and higher is needed, as Java 1.5 language constructs are used.
Question (dep-jrejdk): Do you require the JDK or is the JRE enough? Answer:JRE is enough.
One module JAR, no extras.
Question (deploy-nbm): Can you deploy an NBM via the Update Center? Answer:Yes, can be deployed via UC.
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:Module can be installed anywhere.
Question (deploy-packages): Are packages of your module made inaccessible by not declaring them public? Answer:API package is intentionally public, rest is not 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:Nothing, regular depencency is enough.
Yes.
Question (compat-standards): Does the module implement or define any standards? Is the implementation exact or does it deviate somehow? Answer:Infrastructure module offers SPI for content provider implementors and implements Request-Response pattern for communication between API side and client module side.
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:Yes, module can coexist, as no settings are persistent now.
Question (compat-deprecation): How the introduction of your project influences functionality provided by previous version of the product? Answer:QuickSearch API is new API, so no deprecations for now.
java.io.File
directly?
Answer:
No.
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:Yes, Quick Search UI is plugged into NB window system through xml layer. Moreover, Quick Search API defines layer structure for its clients, explained in use cases reply.
Question (resources-read): Does your module read any resources from layers? For what purpose? Answer:Yes, properly described in use-cases section.
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:No preferences API for now.
org.openide.util.Lookup
or any similar technology to find any components to communicate with? Which ones?
Answer:
No lookup usage.
Question (lookup-register): Do you register anything into lookup for other code to find? Answer:No lookup registration.
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 properties, I plan to use Logger and UI gesture collector in future.
Question (exec-component): Is execution of your code influenced by any (string) property of any of your components? Answer:No properties.
Question (exec-ant-tasks): Do you define or register any ant tasks that other can use? Answer:No ant tasks.
Question (exec-classloader): Does your code create its own class loader(s)? Answer:No own class loader.
Question (exec-reflection): Does your code use Java Reflection to execute other code? Answer:No Java Reflection.
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 external process.
Question (exec-introspection): Does your module use any kind of runtime type information (instanceof
,
work with java.lang.Class
, etc.)?
Answer:
No.
Question (exec-threading): What threading models, if any, does your module adhere to? How the project behaves with respect to threading? Answer:Content providers are called outside EQ thread to not block system UI, RequestProcessor is used. Module's internal data model of provider's results is synchronized to be able to work both with providers and UI code.
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.
No file IO.
Question (format-dnd): Which protocols (if any) does your code understand during Drag & Drop? Answer:No direcr DnD, same as for clipboard.
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 direct clipboard access, just Swing controls are used that communicate with clipboard.
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:Number and speed of individual content providers. See threading anwer for implemented solution.
Question (perf-limit): Are there any hard-coded or practical limits in the number or size of elements your code can handle? Answer:No practical limit.
Question (perf-mem): How much memory does your component consume? Estimate with a relation to the number of windows, etc. Answer:Small memory consumption, only up to a few results items per provider, so say several KBs of data, cleared after each search.
Question (perf-wakeup): Does any piece of your code wake up periodically and do something even when the system is otherwise idle (no user interaction)? Answer:No.
Question (perf-progress): Does your module execute any long-running tasks? Answer:Yes, providers can run their search for a long time. See threading anwer for implemented solution.
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:No huge dialogs.
Question (perf-menus): Does your module use dynamically updated context menus, or context-sensitive actions with complicated and slow enablement logic? Answer:No dynamic context menus.
Question (perf-spi): How the performance of the plugged in code will be enforced? Answer:Code from SPI clients runs in isolated thread and Request-Response API pattern is implemented to enable clients to compute results iteratively and stop whenever desirable.