Bug 35573

*** Issue 35614 has been marked as a duplicate of this issue. ***

Setting TM to 4.2 preliminarily.

I would like to ask for inception review. Attaching javadoc with linked arch
document.

Created attachment 23276 [details]
Zipped javadoc with linked arch document

I suppose the code is in editor/codetemplates, branch completion (right?).

Yes, to compile it's necessary to do the following:
cvs co -r completion editor/codetemplates
cvs co -r codetemplates editor/libsrc

We have found a new usecase that requires an automatic change of a parameter's
value based on change performed to other parameter's value. This will require
calling of the code template processor even after the template was pasted into
the text. I will try to cover this usecase as well.

Y01 Anybody bothered to read index.html? It does not make sence in some parts. 
 
Y02 "Compatible with standards" with what standards? Can they be <api 
type="import"/>ed? 
 
Y03 I am missing usecases for CodeTemplateManager, where are all code 
templates taken from? How the system finds CodeTemplateManager for a document? 
Some properties? Layer API? Lookup? 
 
Y04 What is the relation to code snippets from component palette? Can this API 
work also for them?  
 
Y05 I was looking what to find wrong on the actual classes and interfaces. 
Nothing! Everything is final, Interface has one method. This is the API I 
always wanted to see. One minor thing - I do not see use for 
CodeTemplateDescription constructor, maybe it could be package private. 
 
Y06 What objects are supposed to be immutable and what not? What is the 
usecase for CodeTemplateParameter.setDefaultValue? 

Yardo, thanks for comments.

ad Y01)
I was surprised that the all the usecases got merged together with titles
missing. Is that a feature of the arch html building or is there anything wrong
on my side?
I'll also restore the default answer for arch-where.

ad Y02)
I don't know exactly what the 'standard' stands for. I'll try to clarify that
during review.
 
ad Y03 and Y04)
I was suppossing that the API could work for the code snippets on the component
palette as well. AFAIK there needs to be a GUI for parameter's pre-customization
which could be accomplished by the code template processor (being invoked in the
AWT thread). The only usecase I'm aware of is a generation of the html table
which can be covered by the code template processor calling
CodeTemplateInsertRequest.resetParametrizedText().
The CodeTemplateManager returning list of CodeTemplates was supposed to be the
way for the GUI to fill-in a listbox with the available templates.
 
Y05)
The CodeTemplateDescription's constructor should probably become private as the
persistent templates will be read from the settings by the CT infrastructure and
the temporary code templates usecase (for the code completion) should have an
API-only way of CT creation.
 
Y06)
Both CodeTemplateInsertRequest and CodeTemplateParameter are currently mutable. 
CodeTemplateInsertRequest.resetParametrizedText() mutates the text to be
inserted into the document (and rebuilds the list of parameters). 
CodeTemplateParameter.setDefaultValue() mutates the replacement of the
particular parameter's value inserted into the text.

Arch document updates:
 - insert-text usecase added - on-demand building of the text to be inserted
allows new java infrastructure to reparse it locally
 - parameter-editability usecase added - some parameters should only be updated
automatically by the code template processor but not by the user (e.g. the type
of the iterator variable in 1.5 for loop)

API/SPI updates since inception review:
 - CodeTemplateDescription removed from SPI.
 - CodeTemlateManager.createTemporary() added to API to satisfy the
temporary-code-templates usecase.
 - CodeTemplateInsertRequest.getInsertText() added to satisfy insert-text usecase.
 - CodeTemplateParameter.isEditable() added to satisfy parameter-editability
usecase.
 - naming made more consistent:
   - using "parametrizedText" in methods of CodeTemplate and
CodeTemplateInsertHandler to mark the text containing non-parsed parameters.
   - "insertText" marks the text with the parameters expanded into present
default values.

Now I'm mainly working on the unit tests.
I'm attaching the updated Javadoc + ARC zip.

Created attachment 24149 [details]
Updated Javadoc + arch document

I would like to ask for final API review.

A few minor questions on the syntax & user experience ( I am not qualified to 
comment on anything else)

1. I presume that the user may select any one of the template values which 
will cause all of the corrisponding values to change

2. given that a template can reuse the parameters as above then is it an error 
if the hints are not the same, particually if the hints are contradictory. 
Alternativly is there a rule to say tha the hints should be on the first 
parameter of a given name

3. What is the selection behavior for the replacement of the templates values, 
ie does one click select the value. Can the user tab from one parameter to the 
next and then eventually tab to the final position that is mentioned. or id 
the user forced in a speciac manner to enter parametrs in a a specific order.

4. what is the limits for the hints, and the full syntax. Is the syntax 
extensible? can it contain user defined functions, logic expressions etc?

5.  to expand 4, Can a hint refer to another parameter so as to provide a 
mechanism to relate the default values, so as to achieve

for ({class auto=true} {value default=initialLower(name)} : {collection 
default=paste instanceof="java.util.Collection || Object[] ) {
}

(I hope the syntax is not far off the mark, and that the intent is clear)

this would allow me to copy fred, which is a List<Node>, and apply the template
then the whole template would be filled with the correct values (I would have 
to approve the values

I am personally a fan of JSTL. It would seem to me that this would be a good 
use of the expression functionallity in JSTL to allow the user to extend the 
functions (specifically for the default values, and checks)

I would like to see a mechanism that a user could script a value in the 
template, and an ability to extent that scripting functionallity. JSTL 
provides both of these, very cheaply

The functions that I could see a use for are 
'check' check a value is appropliate
'default' determine a default value (with access to the current parameters)

Here is a link to UI spec:
http://editor.netbeans.org/doc/UISpecs/CodeTemplates/spec.html
it should clarify most of your questions.

ad 4) and 5) We attempt to keep the basic syntax as simple as possible. Target
language editors may define additional hints in a manner specific to them.
Currently only a single type is recognized in the "instanceof" hint but we can
allow for that in the next release.

The review is over -> closing the issue.