This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 136671 - Quick Search API review
Summary: Quick Search API review
Status: RESOLVED FIXED
Alias: None
Product: platform
Classification: Unclassified
Component: Quick Search (show other bugs)
Version: 5.x
Hardware: All All
: P3 blocker (vote)
Assignee: David Simonek
URL: http://wiki.netbeans.org/QuickSearch
Keywords: API_REVIEW
Depends on: 138237
Blocks: 134398
  Show dependency tree
 
Reported: 2008-06-06 16:27 UTC by David Simonek
Modified: 2008-12-22 11:02 UTC (History)
10 users (show)

See Also:
Issue Type: TASK
Exception Reporter:


Attachments
Quick Search SPI Javadoc (77.04 KB, application/octet-stream)
2008-06-06 16:36 UTC, David Simonek
Details
new version of javadoc (71.57 KB, application/x-compressed)
2008-06-11 12:47 UTC, David Simonek
Details

Note You need to log in before you can comment on or make changes to this bug.
Description David Simonek 2008-06-06 16:27:14 UTC
IZ entry for API review of Quick Search API.
Comment 1 David Simonek 2008-06-06 16:32:47 UTC
Main material for review is javadoc of new proposed infrastructure module, org.netbeans.spi.quicksearch which I will
attach in zipped form. javadoc includes all info you may need - proposed architecture, SPI and usage explained.
Comment 2 David Simonek 2008-06-06 16:36:46 UTC
Created attachment 62482 [details]
Quick Search SPI Javadoc
Comment 3 David Simonek 2008-06-06 16:38:37 UTC
Other related materials are:
UI spec - http://xdesign-tools/projects/netbeans/quicksearch_feature/index.html
Wiki page - http://wiki.netbeans.org/QuickSearch
Comment 4 David Simonek 2008-06-06 16:52:01 UTC
Notes for reviewers - I would like to integrate into 6.5 M1, which is tight deadline. So I would like to organize
inception API review meeting early next week and ideally get result of "review passed with some change requests".

So if you want to participate on review, please study javadoc a bit and wait on my meeting invitation. API itself is
very easy and straightforward, as all my APIs :) so don't be scared.

Unfortunately source code is in non public hg repo now, so maybe I can publish some build somewhere for you to try out
current state of feature from user's point of view.
Comment 5 Vitezslav Stejskal 2008-06-07 08:48:31 UTC
I don't seem to be able to access the UIspec. Is http://xdesign-tools/ publicly visible? There are also some links on
your wiki page affected by this.
Comment 6 Jan Becicka 2008-06-09 07:47:45 UTC
Ondro, we should move all relevant info to public wiki. Anyway UI spec is not direct subject of review. Anyway see flash
demos (attached to wiki page) to understand what is this feature about.
Comment 7 Ondrej Langr 2008-06-09 13:50:20 UTC
Thanks for the notice. 

The UI spec as well as storyboards have been moved to public sites:
  UI spec:    http://ui.netbeans.org/docs/ui/quicksearch/index.html
  storyboard: http://ui.netbeans.org/docs/ui/quicksearch/storyboards/index.html
Comment 8 Jaroslav Tulach 2008-06-10 20:29:55 UTC
Y01 Change stability to official - that is the stability this API shall have at the time of release of 6.5 and 
everyone shall be aware that before first public release we are not yet in compatible mode.

Y02 Remove getLookup and CategoryDescription. Create a class named SearchProviderDescription with factory method:
create(Class<? extends SearchProvider>, String prefix, String ...) and in the layer create a registration like:
<folder name="QuickSearch">
  <file name="org-netbeans-mymodule-mypackage-MySearchProviderImplDesc.instance">
    <attr name="instanceCreate" methodvalue="...SearchProviderDescription.create"/>
    <attr name="searchProvider" stringvalue="org.netbeans.mymodule.mypackage.MySearchProvider"/>
    <attr name="category" stringvalue="..."/>
    <attr name="commandPrefix" stringvalue="..."/>
  </file>
</folder>

Y03 Writer a wizard to create all these files, to really help people write SearchProviders
Comment 9 Vitezslav Stejskal 2008-06-11 10:31:40 UTC
VS01: The API does not seem to support multi-keybindings. A multi-keybinding is a sequence of KeyStrokes and some
shortcut profiles (eg. Emacs) heavily use multi-keybindings. I think anywhere where KeyStroke is used now should
actually be Collection<? extends KeyStroke>. Otherwise search providers won't be able to supply correct shortcuts for
the actions they found.
Comment 10 Jan Becicka 2008-06-11 12:01:23 UTC
JB01:
I remember, that requirement was to highlight part of result which match given pattern. Is this use case supported? How?
Comment 11 David Simonek 2008-06-11 12:47:21 UTC
Created attachment 62656 [details]
new version of javadoc
Comment 12 Stanislav Aubrecht 2008-06-11 12:54:34 UTC
SA01: since the search results are pure Runnables there is no way to provide their 'enabled' state. i think it would be
handy especially for context sensitive actions displayed in 'recent search results' section.
Comment 13 David Simonek 2008-06-11 12:58:39 UTC
I attached new version of javadoc, in which:

Y01 is done.

Y02 is done in slightly different way after off line discussion with Jarda. xml registration syntax changed to:

 <folder name="QuickSearch">
      <folder name="MyCategoryID">
          <!--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-MySearchProviderImpll.instance"/>
          <file name="org-netbeans-module2-package3-MySearchProviderImpl2.instance"/>
      </folder>
  </folder>

re Y03: agreed, will do for 6.5 Milestone2

re VS01: good point, agreed, I didn't know about multi shortcuts. Why Collection and not List? Isn't there some order of
individual shortcuts defined?

re JB01: Nice shot, it's not solved yet. I wanted you to help me with this on today's meeting :) Probably we should
enhance SearchResponse to allow providers to specify what should be emphasized. 
Comment 14 Vitezslav Stejskal 2008-06-11 13:16:36 UTC
VS01: Ehrr, yes, sorry, I meant to say List<? extends KeyStroke>.
Comment 15 Max Sauer 2008-06-11 13:37:04 UTC
MS01: What about conflicting names? Is there going to be some way to distinct them from each other (ie, action names)
Comment 16 Ondrej Langr 2008-06-11 13:45:17 UTC
msauer: Users must be able to distinguish between the actions (and know what they are invoking), therefore there should
be no conflicting names. Instead, where there are multiple actions with the same name, we should allow only the one
which makes sense in given context. Or did I misunderstand? Can you give a specific example please? 
Comment 17 Max Sauer 2008-06-11 14:00:40 UTC
olangr: I've meant something like 'Checkout' -- there is such action for both CVS and SVN, entries look same 'Checkout...' => user doesn't know what he's 
invoking. So I had an idea to provide some second-level distinguish for such cases.
Comment 18 Ondrej Langr 2008-06-11 15:22:11 UTC
Thanks, I see. In this case, the names should probably be "CVS checkout" and "SVN checkout". Since the action search
ignores the original context of the actions (in case of checkout, it is given by submenu the actions are present in), we
should probably provide this context by using different action name than is used in the main menu. 

Similarly, we should *not* have "Members" and "File Members" actions for inspect actions in Navigate -> Inspect menu.
Instead, there should be "Inspect Members" and "Inspect File Members" actions.

OL01: Also, we've been previously discussing the possibility of (manual) meta-tagging of actions/options for items
reportedly searched for by different keywords and searching through these meta-tags. I.e., searching for font-size would
bring up the fonts&colors dialog, because it would be meta-tagged, despite that it does not contain the word font-size
anywhere. It is the sound of far future, but does the API allow for that? 
Comment 19 David Simonek 2008-06-11 16:32:00 UTC
Jan, Max, Milan, Vita, Standa and Jarda, thank you for review! Nice to talk to you.

Here comes poor man's opinion document (I know I shouldn't write it myself, but anyway)
----
API was reviewed and accepted with several following requests. Requests must be implemented to final 6.5 release but
don't prevent QuickSearch API to be integrated into 6.5 Milestone 1 build.

Requests:

TCR01: Change KeyStroke to List<? extends KeyStroke>, both in SearchRequest and SearchResponse as requested in VS01, to
support multi key binding.

TCR03: Support html in displayName parameter of SearchResponse.add(....,String displayName, ...) to enable providers to
bold found text or emphasize what they need in display name of result item. Enhance javadoc to remind clients that they
can use basic HTML. That solves JB01.

TCR03: Implement Y03 (Wizard)

TCR04: Have String displayHint in basic SearchResponse.add(....) method as well, because it will be used to solve
duplicate names in UI (see MS01). How and where to display this hint is up to olangr, however tooltip looks probable.

TCR05: Runnable that is returned from providers should be aware that it may be called at a time when run body can't be
performed, because of changed conditions like active context or so on (especially when action is invoked from Recent
Searches list). Providers are expected to signal unsuccessful run by writing into status line and/or beep. I need to
document this in SearchResponse.add(....) javadoc. If this "javadoc API" proves insufficient, we will go with TCA01.

--------------------

Advices:

TCA01: If TCR05 is not enough, then add method SearchResponse.addResult(Action action) so that it's possible to ask
action.isEnabled() and so on. Variant of this is SearchResponse.addResult(StateRunnable action, .....) where
StateRunnable has isEnabled() method. (this solves SA01)

TCA02: Support smart and full type of search, similarly like in code completion - add new method
SearchRequest.getSearchType(). This TCA depends on if and how search types will be needed in UI.

----
Comment 20 David Simonek 2008-06-11 16:37:54 UTC
re OL01: Yes, API do support that. Providers are free to implement any algorithm in SearchProvider.evaluate(...) method,
so Actions provider can search for meta tags anywhere. The biggest work here is to actually create meta tags for actions
and agree on a place where they would be stored. Implementation part isn't hard here.
Comment 21 David Simonek 2008-06-13 14:00:03 UTC
OK, API review is finished, reassigning back to me, but leaving open to not forget on TCRs and TCAs.
Comment 22 David Simonek 2008-06-17 15:40:09 UTC
TCR01 implemented in http://hg.netbeans.org/main/rev/dfed0adb164c

I decided to invalidate TCR04, as UI spec seems to not enforce existence of a hint for result item, so implementation
should be aligned and have it only optional too, as it is now. Please speak up if you think my decision is wrong, thanks.
Comment 24 Quality Engineering 2008-06-27 16:08:32 UTC
Integrated into 'main-golden', available in NB_Trunk_Production #285 build
Changeset: http://hg.netbeans.org/main/rev/5dd3843041d2
User: Dafe Simonek <dsimonek@netbeans.org>
Log: #136671: html tagging in result's htmlDisplayName explained
Comment 25 David Simonek 2008-06-30 16:51:49 UTC
All TCRs completed, closing this api review, thanks.